@synergenius/flow-weaver 0.3.0 → 0.4.1

package/dist/generator/unified.js

@@ -1,7 +1,7 @@
 import { extractStartPorts } from '../ast/workflow-utils.js';
 import { mapToTypeScript } from '../type-mappings.js';
 import { buildNodeArgumentsWithContext, toValidIdentifier } from './code-utils.js';
-import { buildControlFlowGraph, detectBranchingChains, findAllBranchingNodes, findNodesInBranch, performKahnsTopologicalSort, isPerPortScopedChild, } from './control-flow.js';
+import { buildControlFlowGraph, computeParallelLevels, detectBranchingChains, findAllBranchingNodes, findNodesInBranch, performKahnsTopologicalSort, isPerPortScopedChild, } from './control-flow.js';
 import { RESERVED_NODE_NAMES, RESERVED_PORT_NAMES, EXECUTION_STRATEGIES, isStartNode, isExitNode, isExecutePort, isSuccessPort, isFailurePort, } from '../constants.js';
 /**
  * Helper: Determine if an instance has pull execution enabled
@@ -246,6 +246,59 @@ export function generateControlFlowWithExecutionContext(workflow, nodeTypes, isA
             chainMembers.add(chain[i]);
         }
     });
+    // Compute parallel levels for async workflows
+    const perPortScopedChildrenSet = new Set();
+    workflow.instances.forEach((instance) => {
+        if (isPerPortScopedChild(instance, workflow, nodeTypes)) {
+            perPortScopedChildrenSet.add(instance.id);
+        }
+    });
+    const parallelGroupOf = new Map();
+    if (isAsync) {
+        const parallelLevels = computeParallelLevels(cfg, branchingNodes, perPortScopedChildrenSet);
+        for (const group of parallelLevels) {
+            if (group.length < 2)
+                continue;
+            // Filter out nodes that can't be parallelized
+            const eligible = group.filter((id) => {
+                if (nodesInBranches.has(id))
+                    return false;
+                if (pullExecutionNodes.has(id))
+                    return false;
+                if (nodeLevelScopedChildren.has(id))
+                    return false;
+                if (nodesPromotedFromBranches.has(id))
+                    return false;
+                if (chainMembers.has(id))
+                    return false;
+                if (branchingNodes.has(id))
+                    return false;
+                return true;
+            });
+            if (eligible.length >= 2) {
+                for (const nodeId of eligible) {
+                    parallelGroupOf.set(nodeId, eligible);
+                }
+            }
+        }
+    }
+    // Pre-declare execution indices for parallel group nodes
+    if (parallelGroupOf.size > 0) {
+        const declared = new Set();
+        parallelGroupOf.forEach((_, instanceId) => {
+            if (declared.has(instanceId))
+                return;
+            declared.add(instanceId);
+            // Only declare if not already declared by earlier let declarations
+            if (!nodesInBranches.has(instanceId) &&
+                !branchingNodes.has(instanceId) &&
+                !pullExecutionNodes.has(instanceId) &&
+                !nodeLevelScopedChildren.has(instanceId)) {
+                lines.push(`  let ${toValidIdentifier(instanceId)}Idx: number | undefined;`);
+            }
+        });
+        lines.push('');
+    }
     const generatedNodes = new Set();
     const availableVars = new Map();
     Object.keys(extractStartPorts(workflow)).forEach((portName) => {
@@ -272,6 +325,26 @@ export function generateControlFlowWithExecutionContext(workflow, nodeTypes, isA
             lines.push(`  // Node '${instance.id}' skipped: type '${instance.nodeType}' not found`);
             return;
         }
+        // Handle parallel groups: emit Promise.all when hitting first node of a group
+        if (parallelGroupOf.has(instanceId)) {
+            const group = parallelGroupOf.get(instanceId);
+            const ungeneratedGroup = group.filter((id) => !generatedNodes.has(id));
+            if (ungeneratedGroup.length >= 2) {
+                generateParallelGroupWithContext(ungeneratedGroup, workflow, nodeTypes, availableVars, lines, generatedNodes, '  ', isAsync, 'ctx', bundleMode, branchingNodes);
+                // Generate scoped children for each parallel node
+                for (const parallelNodeId of ungeneratedGroup) {
+                    const inst = workflow.instances.find((i) => i.id === parallelNodeId);
+                    if (!inst)
+                        continue;
+                    const nt = nodeTypes.find((n) => n.name === inst.nodeType || n.functionName === inst.nodeType);
+                    if (!nt)
+                        continue;
+                    generateScopedChildrenExecution(inst, nt, workflow, nodeTypes, generatedNodes, availableVars, lines, '  ', branchingNodes, branchRegions, isAsync, bundleMode);
+                }
+                return;
+            }
+            // else: degenerated to 1 or 0, fall through to sequential handling
+        }
         if (branchingNodes.has(instanceId)) {
             // Chain members are generated by their chain head — skip
             if (chainMembers.has(instanceId)) {
@@ -342,7 +415,8 @@ export function generateControlFlowWithExecutionContext(workflow, nodeTypes, isA
                 const nodeUseConst = !nodesInBranches.has(instanceId) &&
                     !branchingNodes.has(instanceId) &&
                     !pullExecutionNodes.has(instanceId) &&
-                    !nodeLevelScopedChildren.has(instanceId);
+                    !nodeLevelScopedChildren.has(instanceId) &&
+                    !parallelGroupOf.has(instanceId);
                 generateNodeCallWithContext(instance, nodeType, workflow, availableVars, lines, nodeTypes, '  ', isAsync, nodeUseConst, undefined, // instanceParent
                 'ctx', // ctxVar
                 bundleMode, false, // skipExecuteGuard
@@ -566,6 +640,52 @@ function generateScopedChildrenExecution(parentInstance, parentNodeType, workflo
     lines.push(`${indent}ctx.mergeScope(${parentInstance.id}_scopedCtx);`);
     lines.push(``);
 }
+/**
+ * Generate a Promise.all block for 2+ parallel nodes in the unified generator.
+ *
+ * Each node's execution code is wrapped in an async IIFE inside Promise.all.
+ * The outer `let` variables for execution indices are assigned inside the IIFEs.
+ */
+function generateParallelGroupWithContext(nodeIds, workflow, nodeTypes, availableVars, lines, generatedNodes, indent, isAsync, ctxVar, bundleMode, branchingNodes) {
+    // Collect code buffers for each node
+    const nodeBuffers = [];
+    for (const nodeId of nodeIds) {
+        const instance = workflow.instances.find((i) => i.id === nodeId);
+        if (!instance)
+            continue;
+        const nodeType = nodeTypes.find((nt) => nt.name === instance.nodeType || nt.functionName === instance.nodeType);
+        if (!nodeType)
+            continue;
+        const nodeLines = [];
+        generateNodeCallWithContext(instance, nodeType, workflow, availableVars, nodeLines, nodeTypes, `${indent}    `, // indent for inside the async IIFE
+        isAsync, false, // useConst = false — outer let declarations
+        undefined, ctxVar, bundleMode, false, branchingNodes);
+        nodeBuffers.push({ id: nodeId, lines: nodeLines });
+    }
+    // Fallback: if only 0-1 nodes remain, emit directly without Promise.all
+    if (nodeBuffers.length < 2) {
+        for (const buf of nodeBuffers) {
+            for (const line of buf.lines) {
+                lines.push(line);
+            }
+            generatedNodes.add(buf.id);
+        }
+        return;
+    }
+    lines.push(`${indent}await Promise.all([`);
+    for (let i = 0; i < nodeBuffers.length; i++) {
+        const buf = nodeBuffers[i];
+        const comma = i < nodeBuffers.length - 1 ? ',' : '';
+        lines.push(`${indent}  (async () => {`);
+        for (const line of buf.lines) {
+            lines.push(line);
+        }
+        lines.push(`${indent}  })()${comma}`);
+        generatedNodes.add(buf.id);
+    }
+    lines.push(`${indent}]);`);
+    lines.push('');
+}
 /**
  * Sort branch nodes topologically based on their dependencies
  *

package/dist/jsdoc-parser.d.ts

@@ -135,6 +135,28 @@ export interface JSDocWorkflowConfig {
             route?: 'ok' | 'fail';
         }>;
     }>;
+    /** @fanOut macros that expand to 1-to-N connections */
+    fanOuts?: Array<{
+        source: {
+            node: string;
+            port: string;
+        };
+        targets: Array<{
+            node: string;
+            port?: string;
+        }>;
+    }>;
+    /** @fanIn macros that expand to N-to-1 connections */
+    fanIns?: Array<{
+        sources: Array<{
+            node: string;
+            port?: string;
+        }>;
+        target: {
+            node: string;
+            port: string;
+        };
+    }>;
     /** @trigger annotation — event name and/or cron schedule */
     trigger?: {
         event?: string;
@@ -287,6 +309,8 @@ export declare class JSDocParser {
      * Format: @path Start -> validator:ok -> classifier -> urgencyRouter:fail -> escalate -> Exit
      */
     private parsePathTag;
+    private parseFanOutTag;
+    private parseFanInTag;
     /**
      * Parse @trigger tag using Chevrotain parser.
      */

package/dist/jsdoc-parser.js

@@ -5,7 +5,7 @@
  */
 import { isExecutePort, isSuccessPort, isFailurePort, isScopedMandatoryPort } from './constants.js';
 import { inferDataTypeFromTS } from './type-mappings.js';
-import { parsePortLine, parseNodeLine, parseConnectLine, parsePositionLine, parseScopeLine, parseMapLine, parsePathLine, parseTriggerLine, parseCancelOnLine, parseThrottleLine, } from './chevrotain-parser/index.js';
+import { parsePortLine, parseNodeLine, parseConnectLine, parsePositionLine, parseScopeLine, parseMapLine, parsePathLine, parseFanOutLine, parseFanInLine, parseTriggerLine, parseCancelOnLine, parseThrottleLine, } from './chevrotain-parser/index.js';
 /**
  * Extract the type of a field from a callback's return type using ts-morph Type API.
  *
@@ -260,6 +260,12 @@ export class JSDocParser {
                 case 'path':
                     this.parsePathTag(tag, config, warnings);
                     break;
+                case 'fanOut':
+                    this.parseFanOutTag(tag, config, warnings);
+                    break;
+                case 'fanIn':
+                    this.parseFanInTag(tag, config, warnings);
+                    break;
                 case 'trigger':
                     this.parseTriggerTag(tag, config, warnings);
                     break;
@@ -864,6 +870,40 @@ export class JSDocParser {
             steps: result.steps,
         });
     }
+    parseFanOutTag(tag, config, warnings) {
+        const comment = tag.getCommentText() || '';
+        const result = parseFanOutLine(`@fanOut ${comment}`, warnings);
+        if (!result) {
+            warnings.push(`Invalid @fanOut tag format: ${comment}`);
+            return;
+        }
+        if (!result.source.port) {
+            warnings.push(`@fanOut source must specify a port: ${comment}`);
+            return;
+        }
+        config.fanOuts = config.fanOuts || [];
+        config.fanOuts.push({
+            source: { node: result.source.node, port: result.source.port },
+            targets: result.targets,
+        });
+    }
+    parseFanInTag(tag, config, warnings) {
+        const comment = tag.getCommentText() || '';
+        const result = parseFanInLine(`@fanIn ${comment}`, warnings);
+        if (!result) {
+            warnings.push(`Invalid @fanIn tag format: ${comment}`);
+            return;
+        }
+        if (!result.target.port) {
+            warnings.push(`@fanIn target must specify a port: ${comment}`);
+            return;
+        }
+        config.fanIns = config.fanIns || [];
+        config.fanIns.push({
+            sources: result.sources,
+            target: { node: result.target.node, port: result.target.port },
+        });
+    }
     /**
      * Parse @trigger tag using Chevrotain parser.
      */

package/dist/mcp/agent-channel.d.ts

@@ -0,0 +1,35 @@
+/**
+ * AgentChannel provides Promise-based pause/resume for workflow execution.
+ *
+ * When a workflow hits a waitForAgent node, the node calls `request()` which
+ * suspends execution on an unresolved Promise. The executor detects the pause
+ * via `onPause()`, and later calls `resume()` to resolve the Promise and
+ * continue execution from exactly where it paused.
+ */
+export declare class AgentChannel {
+    private _resolve;
+    private _reject;
+    private _pauseResolve;
+    private _pausePromise;
+    constructor();
+    /**
+     * Called by the waitForAgent node to suspend execution.
+     * Returns a Promise that resolves when `resume()` is called.
+     */
+    request(agentRequest: object): Promise<object>;
+    /**
+     * Awaited by the executor to detect when the workflow pauses.
+     * Resolves with the agent request data from `request()`.
+     */
+    onPause(): Promise<object>;
+    /**
+     * Called by fw_resume_workflow to continue execution with the agent's result.
+     */
+    resume(result: object): void;
+    /**
+     * Called to fail a pending wait with an error.
+     */
+    fail(reason: string): void;
+    private _createPausePromise;
+}
+//# sourceMappingURL=agent-channel.d.ts.map

package/dist/mcp/agent-channel.js

@@ -0,0 +1,61 @@
+/**
+ * AgentChannel provides Promise-based pause/resume for workflow execution.
+ *
+ * When a workflow hits a waitForAgent node, the node calls `request()` which
+ * suspends execution on an unresolved Promise. The executor detects the pause
+ * via `onPause()`, and later calls `resume()` to resolve the Promise and
+ * continue execution from exactly where it paused.
+ */
+export class AgentChannel {
+    _resolve = null;
+    _reject = null;
+    _pauseResolve = null;
+    _pausePromise;
+    constructor() {
+        this._pausePromise = this._createPausePromise();
+    }
+    /**
+     * Called by the waitForAgent node to suspend execution.
+     * Returns a Promise that resolves when `resume()` is called.
+     */
+    async request(agentRequest) {
+        // Signal the executor that we're pausing
+        this._pauseResolve?.(agentRequest);
+        // Suspend on a new Promise until resume() or fail() is called
+        return new Promise((resolve, reject) => {
+            this._resolve = resolve;
+            this._reject = reject;
+        });
+    }
+    /**
+     * Awaited by the executor to detect when the workflow pauses.
+     * Resolves with the agent request data from `request()`.
+     */
+    onPause() {
+        return this._pausePromise;
+    }
+    /**
+     * Called by fw_resume_workflow to continue execution with the agent's result.
+     */
+    resume(result) {
+        this._resolve?.(result);
+        this._resolve = null;
+        this._reject = null;
+        this._pausePromise = this._createPausePromise();
+    }
+    /**
+     * Called to fail a pending wait with an error.
+     */
+    fail(reason) {
+        this._reject?.(new Error(reason));
+        this._resolve = null;
+        this._reject = null;
+        this._pausePromise = this._createPausePromise();
+    }
+    _createPausePromise() {
+        return new Promise((resolve) => {
+            this._pauseResolve = resolve;
+        });
+    }
+}
+//# sourceMappingURL=agent-channel.js.map

package/dist/mcp/run-registry.d.ts

@@ -0,0 +1,29 @@
+/**
+ * In-memory registry for pending workflow runs that are waiting for agent input.
+ * Used by fw_execute_workflow (to store paused runs) and fw_resume_workflow (to resume them).
+ */
+import type { AgentChannel } from './agent-channel.js';
+export interface PendingRun {
+    runId: string;
+    filePath: string;
+    workflowName?: string;
+    /** The still-pending execution promise. Resolves when workflow completes. */
+    executionPromise: Promise<unknown>;
+    agentChannel: AgentChannel;
+    /** The agent request data that triggered the pause. */
+    request?: object;
+    createdAt: number;
+    /** Temp files to clean up when the run completes or is cancelled. */
+    tmpFiles: string[];
+}
+export declare function storePendingRun(run: PendingRun): void;
+export declare function getPendingRun(runId: string): PendingRun | undefined;
+export declare function removePendingRun(runId: string): void;
+export declare function listPendingRuns(): Array<{
+    runId: string;
+    filePath: string;
+    workflowName?: string;
+    request?: object;
+    createdAt: number;
+}>;
+//# sourceMappingURL=run-registry.d.ts.map

package/dist/mcp/run-registry.js

@@ -0,0 +1,24 @@
+/**
+ * In-memory registry for pending workflow runs that are waiting for agent input.
+ * Used by fw_execute_workflow (to store paused runs) and fw_resume_workflow (to resume them).
+ */
+const pendingRuns = new Map();
+export function storePendingRun(run) {
+    pendingRuns.set(run.runId, run);
+}
+export function getPendingRun(runId) {
+    return pendingRuns.get(runId);
+}
+export function removePendingRun(runId) {
+    pendingRuns.delete(runId);
+}
+export function listPendingRuns() {
+    return Array.from(pendingRuns.values()).map((run) => ({
+        runId: run.runId,
+        filePath: run.filePath,
+        workflowName: run.workflowName,
+        request: run.request,
+        createdAt: run.createdAt,
+    }));
+}
+//# sourceMappingURL=run-registry.js.map

package/dist/mcp/tools-diagram.d.ts

@@ -1,7 +1,7 @@
 /**
  * MCP Diagram Tool - fw_diagram
  *
- * Generates SVG diagrams from workflow files.
+ * Generates SVG or interactive HTML diagrams from workflow files.
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export declare function registerDiagramTools(mcp: McpServer): void;

package/dist/mcp/tools-diagram.js

@@ -1,12 +1,12 @@
 /**
  * MCP Diagram Tool - fw_diagram
  *
- * Generates SVG diagrams from workflow files.
+ * Generates SVG or interactive HTML diagrams from workflow files.
  */
 import { z } from 'zod';
 import * as fs from 'fs';
 import * as path from 'path';
-import { fileToSVG } from '../diagram/index.js';
+import { fileToSVG, fileToHTML } from '../diagram/index.js';
 import { makeToolResult, makeErrorResult } from './response-utils.js';
 export function registerDiagramTools(mcp) {
     mcp.tool('fw_diagram', 'Generate an SVG diagram of a workflow. Returns SVG string or writes to a file.', {
@@ -27,23 +27,31 @@ export function registerDiagramTools(mcp) {
             .boolean()
             .optional()
             .describe('Show port labels on diagram (default: true)'),
+        format: z
+            .enum(['svg', 'html'])
+            .optional()
+            .describe('Output format: svg (default) or html (interactive viewer)'),
     }, async (args) => {
         try {
             const resolvedPath = path.resolve(args.filePath);
             if (!fs.existsSync(resolvedPath)) {
                 return makeErrorResult('FILE_NOT_FOUND', `File not found: ${resolvedPath}`);
             }
-            const svg = fileToSVG(resolvedPath, {
+            const diagramOptions = {
                 workflowName: args.workflowName,
                 theme: args.theme,
                 showPortLabels: args.showPortLabels,
-            });
+            };
+            const isHtml = args.format === 'html';
+            const result = isHtml
+                ? fileToHTML(resolvedPath, diagramOptions)
+                : fileToSVG(resolvedPath, diagramOptions);
             if (args.outputPath) {
                 const outputResolved = path.resolve(args.outputPath);
-                fs.writeFileSync(outputResolved, svg, 'utf-8');
-                return makeToolResult({ written: outputResolved, size: svg.length });
+                fs.writeFileSync(outputResolved, result, 'utf-8');
+                return makeToolResult({ written: outputResolved, size: result.length });
             }
-            return makeToolResult(svg);
+            return makeToolResult(result);
         }
         catch (error) {
             return makeErrorResult('DIAGRAM_ERROR', `Diagram generation failed: ${error instanceof Error ? error.message : String(error)}`);

package/dist/mcp/tools-editor.js

@@ -1,6 +1,8 @@
 import { z } from 'zod';
 import { makeToolResult, makeErrorResult } from './response-utils.js';
 import { executeWorkflowFromFile } from './workflow-executor.js';
+import { AgentChannel } from './agent-channel.js';
+import { storePendingRun, getPendingRun, removePendingRun, listPendingRuns } from './run-registry.js';
 /**
  * Unwrap editor ack responses to flatten double-nested results.
  * Editor returns { requestId, success, result: { actualData } } —
@@ -116,7 +118,8 @@ export function registerEditorTools(mcp, connection, buffer) {
     });
     mcp.tool('fw_execute_workflow', 'Run the current workflow with optional parameters and return the result. ' +
         'Includes per-node execution trace by default (STATUS_CHANGED, VARIABLE_SET events) — ' +
-        'use includeTrace: false to disable.', {
+        'use includeTrace: false to disable. If the workflow pauses at a waitForAgent node, ' +
+        'returns immediately with status "waiting" and a runId — use fw_resume_workflow to continue.', {
         filePath: z
             .string()
             .optional()
@@ -134,11 +137,39 @@ export function registerEditorTools(mcp, connection, buffer) {
         // When filePath is provided, compile and execute directly (no editor needed)
         if (args.filePath) {
             try {
-                const execResult = await executeWorkflowFromFile(args.filePath, args.params, {
+                const channel = new AgentChannel();
+                const runId = `run-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+                const execPromise = executeWorkflowFromFile(args.filePath, args.params, {
                     workflowName: args.workflowName,
                     includeTrace: args.includeTrace,
+                    agentChannel: channel,
                 });
-                return makeToolResult(execResult);
+                // Race between workflow completing and workflow pausing
+                const raceResult = await Promise.race([
+                    execPromise.then((r) => ({ type: 'completed', result: r })),
+                    channel.onPause().then((req) => ({ type: 'paused', request: req })),
+                ]);
+                if (raceResult.type === 'paused') {
+                    // Store the pending run for later resumption
+                    storePendingRun({
+                        runId,
+                        filePath: args.filePath,
+                        workflowName: args.workflowName,
+                        executionPromise: execPromise,
+                        agentChannel: channel,
+                        request: raceResult.request,
+                        createdAt: Date.now(),
+                        tmpFiles: [], // executor manages its own cleanup
+                    });
+                    return makeToolResult({
+                        status: 'waiting',
+                        runId,
+                        request: raceResult.request,
+                        message: 'Workflow paused at waitForAgent node. Use fw_resume_workflow to continue.',
+                    });
+                }
+                // Completed without pausing — return flat result for backward compatibility
+                return makeToolResult(raceResult.result);
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
@@ -154,6 +185,47 @@ export function registerEditorTools(mcp, connection, buffer) {
         const result = await connection.sendCommand('execute-workflow', args.params ?? {});
         return makeToolResult(unwrapAckResult(result));
     });
+    mcp.tool('fw_resume_workflow', 'Resume a paused workflow that is waiting for agent input. ' +
+        'Use this after fw_execute_workflow returns status "waiting".', {
+        runId: z.string().describe('The runId from the waiting execution result'),
+        result: z.record(z.unknown()).describe('The agent result to send back to the workflow'),
+    }, async (args) => {
+        const run = getPendingRun(args.runId);
+        if (!run) {
+            return makeErrorResult('RUN_NOT_FOUND', `No pending run found with ID "${args.runId}". It may have already completed or been cancelled.`);
+        }
+        try {
+            // Resume the workflow by resolving the agent channel's Promise
+            run.agentChannel.resume(args.result);
+            // Wait for the workflow to either complete or pause again
+            const raceResult = await Promise.race([
+                run.executionPromise.then((r) => ({ type: 'completed', result: r })),
+                run.agentChannel.onPause().then((req) => ({ type: 'paused', request: req })),
+            ]);
+            if (raceResult.type === 'paused') {
+                // Workflow paused again at another waitForAgent node
+                run.request = raceResult.request;
+                return makeToolResult({
+                    status: 'waiting',
+                    runId: args.runId,
+                    request: raceResult.request,
+                    message: 'Workflow paused again at another waitForAgent node.',
+                });
+            }
+            // Workflow completed
+            removePendingRun(args.runId);
+            return makeToolResult({ status: 'completed', result: raceResult.result });
+        }
+        catch (err) {
+            removePendingRun(args.runId);
+            const message = err instanceof Error ? err.message : String(err);
+            return makeErrorResult('EXECUTION_ERROR', message);
+        }
+    });
+    mcp.tool('fw_list_pending_runs', 'List workflows that are currently paused waiting for agent input.', {}, async () => {
+        const runs = listPendingRuns();
+        return makeToolResult(runs);
+    });
     mcp.tool('fw_get_workflow_details', 'Get full workflow structure including nodes, connections, types, and positions.', {}, async () => {
         if (!connection.isConnected) {
             return makeErrorResult('EDITOR_NOT_CONNECTED', 'Not connected to the editor. Is the editor running?');

package/dist/mcp/workflow-executor.d.ts

@@ -3,6 +3,7 @@
  * Copies source to a temp file, compiles all workflows in-place, then dynamically imports and executes.
  */
 import type { FwMockConfig } from '../built-in-nodes/mock-types.js';
+import type { AgentChannel } from './agent-channel.js';
 /** A single trace event captured during workflow execution. */
 export interface ExecutionTraceEvent {
     /** The event type (e.g. "NODE_STARTED", "NODE_COMPLETED"). */
@@ -12,6 +13,28 @@ export interface ExecutionTraceEvent {
     /** Additional event data. */
     data?: Record<string, unknown>;
 }
+/** Per-node timing from a trace summary. */
+export interface NodeTiming {
+    /** The node instance ID. */
+    nodeId: string;
+    /** Duration from RUNNING to terminal status, in milliseconds. */
+    durationMs: number;
+}
+/** Summary of workflow execution derived from trace events. */
+export interface TraceSummary {
+    /** Number of unique nodes that emitted STATUS_CHANGED events. */
+    totalNodes: number;
+    /** Nodes that reached SUCCEEDED status. */
+    succeeded: number;
+    /** Nodes that reached FAILED status. */
+    failed: number;
+    /** Nodes that reached CANCELLED status. */
+    cancelled: number;
+    /** Per-node timings (RUNNING → terminal status). */
+    nodeTimings: NodeTiming[];
+    /** Wall-clock duration from first to last trace event, in milliseconds. */
+    totalDurationMs: number;
+}
 /** Result returned after executing a workflow from a file. */
 export interface ExecuteWorkflowResult {
     /** The return value of the executed workflow function. */
@@ -22,6 +45,8 @@ export interface ExecuteWorkflowResult {
     executionTime: number;
     /** Execution trace events, included when `includeTrace` is enabled. */
     trace?: ExecutionTraceEvent[];
+    /** Summary of trace events, included when `includeTrace` is enabled. */
+    summary?: TraceSummary;
 }
 /**
  * Compiles and executes a workflow from a TypeScript source file.
@@ -43,5 +68,8 @@ export declare function executeWorkflowFromFile(filePath: string, params?: Recor
     production?: boolean;
     includeTrace?: boolean;
     mocks?: FwMockConfig;
+    agentChannel?: AgentChannel;
 }): Promise<ExecuteWorkflowResult>;
+/** Compute a concise summary from raw trace events. */
+export declare function computeTraceSummary(trace: ExecutionTraceEvent[]): TraceSummary;
 //# sourceMappingURL=workflow-executor.d.ts.map