@world-engines/dag-flow 0.1.3-alpha.0

package/dist/executor.d.ts

@@ -0,0 +1,136 @@
+import { type DagAgentNode, type DagDocument, type DagJson, type DagNode, type DagScriptNode, type DagValidationIssue } from "./document.js";
+export type DagNodeRunStatus = "succeeded" | "failed" | "skipped" | "aborted";
+export interface DagNodeRunResult {
+    readonly status: DagNodeRunStatus;
+    readonly input?: DagJson;
+    readonly outputs?: Readonly<Record<string, DagJson>>;
+    readonly error?: string;
+    /** 后端已有的真实 dispatch receipt，原样透传；执行器不结算或计费。 */
+    readonly receipt?: unknown;
+}
+/** Agent 是字符串边界：内部 mixed JSON 仅在这里序列化。 */
+export interface DagAgentInvocation {
+    readonly node: DagAgentNode;
+    readonly input: string;
+    readonly signal?: AbortSignal;
+}
+export type DagAgentInvocationResult = {
+    readonly status: "success";
+    readonly body: string;
+    readonly receipt?: unknown;
+} | {
+    readonly status: "error";
+    readonly error: string;
+    readonly receipt?: unknown;
+};
+/** 脚本保持 DAG JSON 值，不应在进入 sandbox 前提前字符串化。 */
+export interface DagScriptInvocation {
+    readonly node: DagScriptNode;
+    readonly input: DagJson;
+    readonly signal?: AbortSignal;
+}
+export interface DagScriptResult {
+    readonly path: string;
+    readonly body: DagJson;
+}
+export interface ExecuteDagDocumentOptions {
+    readonly input: string;
+    /** 可选的导演上下文；缺省时保持旧的纯文本输入协议。 */
+    readonly history?: readonly DagHistoryMessage[];
+    readonly historyWindow?: number;
+    readonly scene?: unknown;
+    readonly currentWorldTimeMs?: number;
+    readonly nearestTimeTriggerAtMs?: number;
+    /** Director 输出门控；返回错误文本时按 retry 次数重新请求。 */
+    readonly directorOutputRetries?: number;
+    readonly validateDirectorOutput?: (output: string, context: Readonly<{
+        input: string;
+        attempt: number;
+    }>) => string | void | Promise<string | void>;
+    readonly onDirectorRetry?: (event: Readonly<{
+        attempt: number;
+        reason: string;
+    }>) => void | Promise<void>;
+    readonly signal?: AbortSignal;
+    /** 由系统注入的 Director 正文；不能被作者节点配置替换。 */
+    readonly directorOutput?: string | ((input: string, signal?: AbortSignal) => string | Promise<string>);
+    /** 真实场记/写手阶段。受控插槽文档要求两个回调均存在，缺失即失败。 */
+    readonly runSystemStage?: (invocation: DagSystemStageInvocation) => DagSystemStageResult | Promise<DagSystemStageResult>;
+    readonly invokeAgent?: (invocation: DagAgentInvocation) => unknown | Promise<unknown>;
+    readonly runScript?: (invocation: DagScriptInvocation) => unknown | Promise<unknown>;
+    /** Text Output 是字符串边界：mixed JSON 在发射前才序列化。 */
+    readonly emitText?: (event: {
+        readonly node: DagNode;
+        readonly input: string;
+        readonly signal?: AbortSignal;
+    }) => void | Promise<void>;
+    readonly onNodeResult?: (node: DagNode, result: DagNodeRunResult) => void | Promise<void>;
+}
+export interface DagSystemStageInvocation {
+    readonly stage: "scribe" | "writer";
+    readonly input: DagJson;
+    readonly signal?: AbortSignal;
+}
+export interface DagSystemStageResult {
+    readonly body: DagJson;
+    readonly receipt?: unknown;
+}
+export interface DagHistoryMessage {
+    readonly role: "user" | "assistant";
+    readonly content: string;
+    readonly createdAtMs?: number;
+}
+/**
+ * 手稿通过场记校验后的一次性扇出结果。Writer 与演出组共享同一份不可变手稿，
+ * 两类工作在同一调度点启动，任一分支失败不会取消另一分支；调用方决定失败如何呈现。
+ */
+export interface ManuscriptFanoutOptions<TWriter, TPerformance> {
+    readonly manuscript: string;
+    readonly scene?: unknown;
+    readonly signal?: AbortSignal;
+    readonly runWriter: (input: Readonly<{
+        manuscript: string;
+        scene?: unknown;
+        signal?: AbortSignal;
+    }>) => TWriter | Promise<TWriter>;
+    readonly runPerformance?: (input: Readonly<{
+        manuscript: string;
+        scene?: unknown;
+        signal?: AbortSignal;
+    }>) => TPerformance | Promise<TPerformance>;
+}
+export interface ManuscriptFanoutResult<TWriter, TPerformance> {
+    readonly writer: TWriter;
+    readonly performance?: TPerformance;
+}
+/**
+ * 在手稿确定后并行启动 Writer 和可选摄影/语音演出组。
+ * 成功结果会等待两条分支完成；失败立即向调用方传播，另一分支仍可自行完成。
+ * provider 自身通过 signal 响应取消，不在这里隐式重试或吞掉错误。
+ */
+export declare function runManuscriptFanout<TWriter, TPerformance>(options: ManuscriptFanoutOptions<TWriter, TPerformance>): Promise<ManuscriptFanoutResult<TWriter, TPerformance>>;
+/** 同一 DAG 重试期间复用召回结果，避免再次计费或重复查询。 */
+export declare function cachedDagRecall<T>(cache: Map<string, T>, key: string, producer: () => T | Promise<T>): Promise<T>;
+/** 将场景信息中的时间字段转换为中文绝对时间，避免模型误读 epoch。 */
+export declare function formatSceneTimestamps(value: unknown): unknown;
+export interface DagRunResult {
+    readonly status: "completed" | "failed" | "aborted";
+    /** 失败时的可展示原因；受控插槽不会把阶段失败伪装为 skipped 成功。 */
+    readonly error?: string;
+    readonly node_results: Readonly<Record<string, DagNodeRunResult>>;
+    readonly emitted_text: readonly string[];
+    readonly receipts: readonly unknown[];
+    /** 受控系统阶段的真实回执；仅 insertion_slots 文档产生。 */
+    readonly stage_results?: Readonly<Partial<Record<"scribe" | "writer", DagSystemStageResult>>>;
+}
+export declare class DagDocumentValidationError extends Error {
+    readonly issues: readonly DagValidationIssue[];
+    constructor(issues: readonly DagValidationIssue[]);
+}
+/**
+ * 每个节点只有一条输入依赖，依赖完成即开始运行。分支间不互相等待，
+ * 只有 AbortSignal 会阻止尚未开始的节点并要求运行中的 provider 自行中止。
+ */
+export declare function executeDagDocument(document: DagDocument, options: ExecuteDagDocumentOptions): Promise<DagRunResult>;
+export declare function isDagAgentInvocationResult(value: unknown): value is DagAgentInvocationResult;
+export declare function isDagScriptResult(value: unknown): value is DagScriptResult;

package/dist/executor.js

@@ -0,0 +1,543 @@
+import { dagMixedToString, isDagJson, DAG_STAGE_BOUNDARIES, upgradeDagDocument, validateDagDocument, } from "./document.js";
+/**
+ * 在手稿确定后并行启动 Writer 和可选摄影/语音演出组。
+ * 成功结果会等待两条分支完成；失败立即向调用方传播，另一分支仍可自行完成。
+ * provider 自身通过 signal 响应取消，不在这里隐式重试或吞掉错误。
+ */
+export async function runManuscriptFanout(options) {
+    if (typeof options.manuscript !== "string" || options.manuscript.length === 0) {
+        throw new TypeError("manuscript_required");
+    }
+    if (options.signal?.aborted)
+        throw new DOMException("The operation was aborted", "AbortError");
+    const input = Object.freeze({
+        manuscript: options.manuscript,
+        ...(options.scene === undefined ? {} : { scene: freezeSceneSnapshot(options.scene) }),
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+    });
+    const writerPromise = Promise.resolve().then(() => options.runWriter(input));
+    const performancePromise = options.runPerformance === undefined
+        ? undefined
+        : Promise.resolve().then(() => options.runPerformance(input));
+    if (performancePromise === undefined)
+        return { writer: await writerPromise };
+    // 同时订阅两个分支的失败，避免较快的演出失败在等待 Writer 时成为未处理拒绝。
+    const [writer, performance] = await Promise.all([writerPromise, performancePromise]);
+    return { writer, performance };
+}
+function freezeSceneSnapshot(scene) {
+    if (!isDagJson(scene))
+        throw new TypeError("manuscript_scene_invalid");
+    const snapshot = structuredClone(scene);
+    const freeze = (value) => {
+        if (value !== null && typeof value === "object") {
+            for (const child of Object.values(value))
+                freeze(child);
+            Object.freeze(value);
+        }
+        return value;
+    };
+    return freeze(snapshot);
+}
+/** 同一 DAG 重试期间复用召回结果，避免再次计费或重复查询。 */
+export async function cachedDagRecall(cache, key, producer) {
+    if (cache.has(key))
+        return cache.get(key);
+    const value = await producer();
+    cache.set(key, value);
+    return value;
+}
+/** 将场景信息中的时间字段转换为中文绝对时间，避免模型误读 epoch。 */
+export function formatSceneTimestamps(value) {
+    if (Array.isArray(value))
+        return value.map(formatSceneTimestamps);
+    if (value === null || typeof value !== "object")
+        return value;
+    const source = value;
+    const result = {};
+    for (const [key, child] of Object.entries(source)) {
+        const normalized = key.toLowerCase();
+        const isTimestamp = normalized.includes("timestamp") || normalized.endsWith("_at_ms") || normalized.endsWith("_ts_ms");
+        if (isTimestamp) {
+            const numeric = typeof child === "number" ? child : typeof child === "string" && /^-?\\d+(?:\\.\\d+)?$/u.test(child) ? Number(child) : NaN;
+            if (Number.isFinite(numeric)) {
+                const date = new Date(numeric < 1e12 ? numeric * 1000 : numeric);
+                if (!Number.isNaN(date.getTime())) {
+                    const p = (n) => String(n).padStart(2, "0");
+                    result[key] = `${date.getUTCFullYear()}年${p(date.getUTCMonth() + 1)}月${p(date.getUTCDate())}日 ${p(date.getUTCHours())}时${p(date.getUTCMinutes())}分${p(date.getUTCSeconds())}秒`;
+                    continue;
+                }
+            }
+        }
+        result[key] = formatSceneTimestamps(child);
+    }
+    return result;
+}
+function directorContext(input, options) {
+    if (options.history === undefined && options.scene === undefined && options.currentWorldTimeMs === undefined && options.nearestTimeTriggerAtMs === undefined)
+        return dagMixedToString(input);
+    const window = options.historyWindow === undefined ? 4 : Math.max(0, Math.floor(options.historyWindow));
+    const evenWindow = window % 2 === 0 ? window : window - 1;
+    const history = (options.history ?? []).slice(-evenWindow);
+    return JSON.stringify({
+        input: dagMixedToString(input),
+        history,
+        scene: options.scene === undefined ? undefined : formatSceneTimestamps(options.scene),
+        currentWorldTimeMs: options.currentWorldTimeMs,
+        nearestTimeTriggerAtMs: options.nearestTimeTriggerAtMs,
+    });
+}
+export class DagDocumentValidationError extends Error {
+    issues;
+    constructor(issues) {
+        super("dag_document_invalid");
+        this.name = "DagDocumentValidationError";
+        this.issues = issues;
+    }
+}
+/**
+ * 每个节点只有一条输入依赖，依赖完成即开始运行。分支间不互相等待，
+ * 只有 AbortSignal 会阻止尚未开始的节点并要求运行中的 provider 自行中止。
+ */
+export async function executeDagDocument(document, options) {
+    // v1 文档只在执行入口做一次显式升级；之后统一按 v2 阶段边界运行。
+    const normalized = document.schema_version === 1 ? upgradeDagDocument(document).document : document;
+    const validation = validateDagDocument(normalized, { mode: "run" });
+    if (!validation.ok)
+        throw new DagDocumentValidationError(validation.issues);
+    if (normalized.stage_flow?.enabled === true)
+        return await executeStageFlow(normalized, options);
+    if (normalized.insertion_slots !== undefined)
+        return await executeControlledSlots(normalized, options);
+    const nodes = new Map(normalized.nodes.map((node) => [node.id, node]));
+    const outgoing = indexOutgoing(normalized.edges);
+    // 作者可合法使用 __proto__ 作为节点 id；结果表不能继承 Object.prototype。
+    const results = Object.create(null);
+    const emittedText = [];
+    const receipts = [];
+    const scheduled = new Set();
+    const active = new Set();
+    let aborted = false;
+    let terminal = false;
+    const report = async (node, result) => {
+        results[node.id] = result;
+        if (result.receipt !== undefined)
+            receipts.push(result.receipt);
+        await options.onNodeResult?.(node, result);
+    };
+    const schedule = (node, input) => {
+        if (scheduled.has(node.id))
+            return;
+        scheduled.add(node.id);
+        const task = (async () => {
+            if (aborted || terminal || options.signal?.aborted) {
+                aborted = true;
+                await report(node, { status: "skipped", input });
+                return;
+            }
+            const outcome = await executeNode(node, input, options, emittedText);
+            await report(node, outcome);
+            if (outcome.status === "aborted") {
+                aborted = true;
+                return;
+            }
+            // 文本出口是用户可见的 terminal；已启动的 provider 仍由自身完成，
+            // 尚未启动的分支跳过，避免一轮回合继续向多个出口发射正文。
+            if (outcome.status === "succeeded" && node.kind === "text_output" && !node.system && normalized.execution?.terminal_on_text_output === true)
+                terminal = true;
+            if (outcome.status === "succeeded" && outcome.outputs && !terminal)
+                propagate(node, outcome.outputs);
+        })();
+        active.add(task);
+        void task.then(() => active.delete(task), () => active.delete(task));
+    };
+    const propagate = (from, outputs) => {
+        if (aborted || options.signal?.aborted)
+            return;
+        for (const [port, value] of Object.entries(outputs))
+            for (const edge of outgoing.get(key(from.id, port)) ?? []) {
+                const target = nodes.get(edge.to.node_id);
+                if (target)
+                    schedule(target, value);
+            }
+    };
+    const user = nodes.get("user_input");
+    if (options.signal?.aborted) {
+        aborted = true;
+        scheduled.add(user.id);
+        await report(user, { status: "skipped", input: options.input });
+    }
+    else {
+        scheduled.add(user.id);
+        await report(user, { status: "succeeded", input: options.input, outputs: { output: options.input } });
+        propagate(user, { output: options.input });
+    }
+    while (active.size > 0)
+        await Promise.all([...active]);
+    if (aborted || options.signal?.aborted)
+        aborted = true;
+    for (const node of document.nodes)
+        if (!results[node.id])
+            await report(node, { status: "skipped" });
+    return {
+        status: aborted ? "aborted" : Object.values(results).some((result) => result.status === "failed") ? "failed" : "completed",
+        node_results: results,
+        emitted_text: emittedText,
+        receipts,
+    };
+}
+/** v2 阶段图按 start → 作者节点 → handoff 的真实序列化边执行。 */
+async function executeStageFlow(document, options) {
+    const nodes = new Map(document.nodes.map((node) => [node.id, node]));
+    const outgoing = indexOutgoing(document.edges);
+    const results = Object.create(null);
+    const emittedText = [];
+    const receipts = [];
+    const stageResults = {};
+    let aborted = false;
+    let terminal = false;
+    const report = async (node, result) => {
+        results[node.id] = result;
+        if (result.receipt !== undefined)
+            receipts.push(result.receipt);
+        await options.onNodeResult?.(node, result);
+    };
+    const stop = async (error) => {
+        for (const node of document.nodes)
+            if (!results[node.id])
+                await report(node, { status: "skipped" });
+        const status = aborted || options.signal?.aborted ? "aborted" : error === undefined ? "completed" : "failed";
+        return status === "failed"
+            ? { status, error: error, node_results: results, emitted_text: emittedText, receipts, stage_results: stageResults }
+            : { status, node_results: results, emitted_text: emittedText, receipts, stage_results: stageResults };
+    };
+    const runLinear = async (id, input) => {
+        let current = nodes.get(id);
+        let body = input;
+        const seen = new Set();
+        while (current) {
+            if (seen.has(current.id))
+                return { kind: "failed", error: "stage_cycle" };
+            seen.add(current.id);
+            if (options.signal?.aborted) {
+                aborted = true;
+                await report(current, { status: "aborted", input: body });
+                return { kind: "failed", error: "aborted" };
+            }
+            if (current.kind === "stage_handoff") {
+                await report(current, { status: "succeeded", input: body });
+                return { kind: "handoff", body };
+            }
+            if (current.kind === "stage_start") {
+                await report(current, { status: "succeeded", input: body, outputs: { output: body } });
+                const edge = oneOutputEdge(outgoing, current.id, "output");
+                if (!edge)
+                    return { kind: "failed", error: `stage_start_disconnected:${current.id}` };
+                current = nodes.get(edge.to.node_id);
+                continue;
+            }
+            const outcome = await executeNode(current, body, options, emittedText);
+            await report(current, outcome);
+            if (outcome.status === "aborted") {
+                aborted = true;
+                return { kind: "failed", error: "aborted" };
+            }
+            if (current.kind === "text_output") {
+                if (outcome.status === "succeeded") {
+                    terminal = true;
+                    return { kind: "terminal" };
+                }
+                return { kind: "failed", error: outcome.error ?? "text_output_failed" };
+            }
+            if (outcome.status !== "succeeded" || !outcome.outputs)
+                return { kind: "failed", error: outcome.error ?? "stage_node_failed" };
+            const output = Object.entries(outcome.outputs).find(([port]) => oneOutputEdge(outgoing, current.id, port) !== undefined);
+            if (!output)
+                return { kind: "failed", error: `stage_output_disconnected:${current.id}` };
+            const edge = oneOutputEdge(outgoing, current.id, output[0]);
+            if (!edge)
+                return { kind: "failed", error: `stage_output_disconnected:${current.id}` };
+            body = output[1];
+            current = nodes.get(edge.to.node_id);
+        }
+        return { kind: "failed", error: "stage_target_missing" };
+    };
+    const user = nodes.get("user_input");
+    await report(user, options.signal?.aborted ? { status: "skipped", input: options.input } : { status: "succeeded", input: options.input, outputs: { output: options.input } });
+    if (options.signal?.aborted) {
+        aborted = true;
+        return await stop();
+    }
+    const before = await runLinear(DAG_STAGE_BOUNDARIES[0].start_id, options.input);
+    if (before.kind === "terminal")
+        return await stop();
+    if (before.kind === "failed")
+        return await stop(before.error);
+    const director = nodes.get("director");
+    const directorOutcome = await executeNode(director, before.body, options, emittedText);
+    await report(director, directorOutcome);
+    const manuscript = directorOutcome.status === "succeeded" ? directorOutcome.outputs?.output : undefined;
+    if (manuscript === undefined)
+        return await stop(directorOutcome.error ?? "director_failed");
+    const scribed = await runRequiredStage("scribe", manuscript, options, stageResults, receipts);
+    if (!scribed.ok)
+        return await stop(scribed.error);
+    const afterScribe = await runLinear(DAG_STAGE_BOUNDARIES[1].start_id, scribed.body);
+    if (afterScribe.kind === "terminal")
+        return await stop();
+    if (afterScribe.kind === "failed")
+        return await stop(afterScribe.error);
+    const written = await runRequiredStage("writer", afterScribe.body, options, stageResults, receipts);
+    if (!written.ok)
+        return await stop(written.error);
+    const afterWriter = await runLinear(DAG_STAGE_BOUNDARIES[2].start_id, written.body);
+    if (afterWriter.kind === "terminal")
+        return await stop();
+    if (afterWriter.kind === "failed")
+        return await stop(afterWriter.error);
+    const output = nodes.get("text_output");
+    const outputOutcome = await executeNode(output, afterWriter.body, options, emittedText);
+    await report(output, outputOutcome);
+    return await stop(outputOutcome.status === "succeeded" || terminal ? undefined : outputOutcome.error ?? "text_output_failed");
+}
+function oneOutputEdge(outgoing, nodeId, port) {
+    const edges = outgoing.get(key(nodeId, port)) ?? [];
+    return edges.length === 1 ? edges[0] : undefined;
+}
+async function runRequiredStage(stage, input, options, stageResults, receipts) {
+    if (!options.runSystemStage)
+        return { ok: false, error: `system_stage_required:${stage}` };
+    try {
+        const result = await options.runSystemStage({ stage, input, ...(options.signal === undefined ? {} : { signal: options.signal }) });
+        if (!isSystemStageResult(result))
+            return { ok: false, error: `system_stage_result_invalid:${stage}` };
+        stageResults[stage] = result;
+        if (result.receipt !== undefined)
+            receipts.push(result.receipt);
+        return { ok: true, body: result.body };
+    }
+    catch (error) {
+        return { ok: false, error: errorMessage(error) };
+    }
+}
+/**
+ * 受控插槽不是普通旁支：三个槽按系统回合顺序串行消费并产出数据。
+ * 文档只能登记 Agent id，不能改写 user → director → scribe → writer → text 的主线。
+ */
+async function executeControlledSlots(document, options) {
+    const nodes = new Map(document.nodes.map((node) => [node.id, node]));
+    const results = Object.create(null);
+    const emittedText = [];
+    const receipts = [];
+    const stageResults = {};
+    let aborted = false;
+    const report = async (node, result) => {
+        results[node.id] = result;
+        if (result.receipt !== undefined)
+            receipts.push(result.receipt);
+        await options.onNodeResult?.(node, result);
+    };
+    const stop = async (error) => {
+        for (const node of document.nodes)
+            if (!results[node.id])
+                await report(node, { status: "skipped" });
+        const status = aborted || options.signal?.aborted ? "aborted" : "failed";
+        return { status, ...(status === "failed" ? { error } : {}), node_results: results, emitted_text: emittedText, receipts, stage_results: stageResults };
+    };
+    const runSlot = async (slot, input) => {
+        let body = input;
+        for (const id of document.insertion_slots?.[slot] ?? []) {
+            const node = nodes.get(id);
+            if (!node || node.kind !== "agent")
+                return { ok: false, error: `insertion_slot_agent_missing:${id}` };
+            const outcome = await runAgent(node, body, options);
+            await report(node, outcome);
+            if (outcome.status === "aborted") {
+                aborted = true;
+                return { ok: false, error: "aborted" };
+            }
+            const success = outcome.status === "succeeded" ? outcome.outputs?.success : undefined;
+            if (success === undefined)
+                return { ok: false, error: outcome.error ?? (outcome.outputs?.error === undefined ? "insertion_slot_agent_failed" : dagMixedToString(outcome.outputs.error)) };
+            body = success;
+        }
+        return { ok: true, body };
+    };
+    const runStage = async (stage, input) => {
+        if (!options.runSystemStage)
+            return { ok: false, error: `system_stage_required:${stage}` };
+        try {
+            const result = await options.runSystemStage({ stage, input, ...(options.signal === undefined ? {} : { signal: options.signal }) });
+            if (!isSystemStageResult(result))
+                return { ok: false, error: `system_stage_result_invalid:${stage}` };
+            if (options.signal?.aborted) {
+                aborted = true;
+                return { ok: false, error: "aborted" };
+            }
+            stageResults[stage] = result;
+            if (result.receipt !== undefined)
+                receipts.push(result.receipt);
+            return { ok: true, body: result.body };
+        }
+        catch (error) {
+            if (options.signal?.aborted || isAbortError(error)) {
+                aborted = true;
+                return { ok: false, error: "aborted" };
+            }
+            return { ok: false, error: errorMessage(error) };
+        }
+    };
+    const user = nodes.get("user_input");
+    await report(user, options.signal?.aborted ? { status: "skipped", input: options.input } : { status: "succeeded", input: options.input, outputs: { output: options.input } });
+    if (options.signal?.aborted) {
+        aborted = true;
+        return await stop("aborted");
+    }
+    const before = await runSlot("before_director", options.input);
+    if (!before.ok)
+        return await stop(before.error);
+    const director = nodes.get("director");
+    const directorOutcome = await executeNode(director, before.body, options, emittedText);
+    await report(director, directorOutcome);
+    const manuscript = directorOutcome.status === "succeeded" ? directorOutcome.outputs?.output : undefined;
+    if (manuscript === undefined)
+        return await stop(directorOutcome.error ?? "director_failed");
+    const scribed = await runStage("scribe", manuscript);
+    if (!scribed.ok)
+        return await stop(scribed.error);
+    const afterScribe = await runSlot("after_scribe", scribed.body);
+    if (!afterScribe.ok)
+        return await stop(afterScribe.error);
+    const written = await runStage("writer", afterScribe.body);
+    if (!written.ok)
+        return await stop(written.error);
+    const afterWriter = await runSlot("after_writer", written.body);
+    if (!afterWriter.ok)
+        return await stop(afterWriter.error);
+    const output = nodes.get("text_output");
+    const outputOutcome = await executeNode(output, afterWriter.body, options, emittedText);
+    await report(output, outputOutcome);
+    if (outputOutcome.status === "aborted")
+        aborted = true;
+    for (const node of document.nodes)
+        if (!results[node.id])
+            await report(node, { status: "skipped" });
+    return { status: aborted ? "aborted" : outputOutcome.status === "succeeded" ? "completed" : "failed", node_results: results, emitted_text: emittedText, receipts, stage_results: stageResults };
+}
+async function executeNode(node, input, options, emittedText) {
+    try {
+        if (options.signal?.aborted)
+            return { status: "aborted", input };
+        switch (node.kind) {
+            case "director": {
+                if (options.directorOutput === undefined)
+                    return { status: "failed", input, error: "director_output_required" };
+                const promptInput = directorContext(input, options);
+                const maxAttempts = options.directorOutputRetries ?? 1;
+                if (!Number.isSafeInteger(maxAttempts) || maxAttempts < 1)
+                    return { status: "failed", input, error: "director_retry_limit_invalid" };
+                for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+                    const output = typeof options.directorOutput === "string" ? options.directorOutput : await options.directorOutput(promptInput, options.signal);
+                    if (typeof output !== "string")
+                        return { status: "failed", input, error: "director_output_invalid" };
+                    if (options.signal?.aborted)
+                        return { status: "aborted", input };
+                    const reason = await options.validateDirectorOutput?.(output, { input: promptInput, attempt });
+                    if (reason === undefined || attempt >= maxAttempts) {
+                        if (reason !== undefined)
+                            return { status: "failed", input, error: reason };
+                        return { status: "succeeded", input, outputs: { output } };
+                    }
+                    await options.onDirectorRetry?.({ attempt, reason });
+                }
+                return { status: "failed", input, error: "director_output_invalid" };
+            }
+            case "agent": return await runAgent(node, input, options);
+            case "script": return await runScript(node, input, options);
+            case "text_output": {
+                const text = dagMixedToString(input);
+                await options.emitText?.({ node, input: text, ...(options.signal ? { signal: options.signal } : {}) });
+                if (options.signal?.aborted)
+                    return { status: "aborted", input };
+                emittedText.push(text);
+                return { status: "succeeded", input };
+            }
+            case "user_input": return { status: "succeeded", input, outputs: { output: input } };
+            case "stage_start":
+            case "stage_handoff": return { status: "failed", input, error: "stage_boundary_requires_stage_flow" };
+        }
+    }
+    catch (error) {
+        if (options.signal?.aborted || isAbortError(error))
+            return { status: "aborted", input };
+        return { status: "failed", input, error: errorMessage(error) };
+    }
+}
+async function runAgent(node, input, options) {
+    if (!options.invokeAgent)
+        return { status: "failed", input, error: "invoke_agent_required" };
+    const candidate = await options.invokeAgent({ node, input: dagMixedToString(input), ...(options.signal ? { signal: options.signal } : {}) });
+    if (!isDagAgentInvocationResult(candidate))
+        return { status: "failed", input, error: "agent_invocation_result_invalid" };
+    if (options.signal?.aborted)
+        return { status: "aborted", input };
+    if (candidate.status === "error")
+        return {
+            status: "succeeded", input, outputs: { error: candidate.error }, ...(candidate.receipt === undefined ? {} : { receipt: candidate.receipt }),
+        };
+    if (node.config.require_json && !isStrictJson(candidate.body))
+        return {
+            status: "succeeded", input, outputs: { error: "agent_output_invalid_json" }, ...(candidate.receipt === undefined ? {} : { receipt: candidate.receipt }),
+        };
+    return {
+        status: "succeeded", input, outputs: { success: candidate.body }, ...(candidate.receipt === undefined ? {} : { receipt: candidate.receipt }),
+    };
+}
+async function runScript(node, input, options) {
+    if (!options.runScript)
+        return { status: "failed", input, error: "run_script_required" };
+    const candidate = await options.runScript({ node, input, ...(options.signal ? { signal: options.signal } : {}) });
+    if (!isDagScriptResult(candidate))
+        return { status: "failed", input, error: "script_main_result_invalid" };
+    if (options.signal?.aborted)
+        return { status: "aborted", input };
+    const allowedPaths = node.config.paths?.length ? node.config.paths : ["output"];
+    if (!allowedPaths.includes(candidate.path))
+        return { status: "failed", input, error: "script_main_path_invalid" };
+    return { status: "succeeded", input, outputs: { [candidate.path]: candidate.body } };
+}
+export function isDagAgentInvocationResult(value) {
+    if (!isRecord(value))
+        return false;
+    if (value.status === "success")
+        return typeof value.body === "string";
+    return value.status === "error" && typeof value.error === "string";
+}
+export function isDagScriptResult(value) {
+    if (!isRecord(value) || Object.keys(value).length !== 2 || !Object.hasOwn(value, "path") || !Object.hasOwn(value, "body"))
+        return false;
+    return typeof value.path === "string" && value.path.length > 0 && isDagJson(value.body);
+}
+function isSystemStageResult(value) {
+    return isRecord(value) && Object.hasOwn(value, "body") && isDagJson(value.body);
+}
+function indexOutgoing(edges) {
+    const result = new Map();
+    for (const edge of edges) {
+        const list = result.get(key(edge.from.node_id, edge.from.port)) ?? [];
+        list.push(edge);
+        result.set(key(edge.from.node_id, edge.from.port), list);
+    }
+    return result;
+}
+/** ID 与 port 可包含冒号，故使用无歧义 JSON 元组作为索引键。 */
+function key(nodeId, port) { return JSON.stringify([nodeId, port]); }
+function isStrictJson(value) { try {
+    return isDagJson(JSON.parse(value));
+}
+catch {
+    return false;
+} }
+function isRecord(value) { return value !== null && typeof value === "object" && !Array.isArray(value); }
+function isAbortError(error) { return error instanceof Error && error.name === "AbortError"; }
+function errorMessage(error) { return error instanceof Error ? error.message : typeof error === "string" ? error : "unknown_error"; }