@synergenius/flow-weaver 0.2.1 → 0.4.0

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/server.js

@@ -11,6 +11,7 @@ import { registerPatternTools } from './tools-pattern.js';
 import { registerExportTools } from './tools-export.js';
 import { registerMarketplaceTools } from './tools-marketplace.js';
 import { registerDiagramTools } from './tools-diagram.js';
+import { registerDocsTools } from './tools-docs.js';
 import { registerResources } from './resources.js';
 function parseEventFilterFromEnv() {
     const filter = {};
@@ -70,6 +71,7 @@ export async function startMcpServer(options) {
     registerExportTools(mcp);
     registerMarketplaceTools(mcp);
     registerDiagramTools(mcp);
+    registerDocsTools(mcp);
     registerResources(mcp, connection, buffer);
     // Connect transport (only in stdio MCP mode)
     if (!options._testDeps && options.stdio) {

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-docs.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerDocsTools(mcp: McpServer): void;
+//# sourceMappingURL=tools-docs.d.ts.map

package/dist/mcp/tools-docs.js

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import { listTopics, readTopic, searchDocs } from '../docs/index.js';
+import { makeToolResult, makeErrorResult } from './response-utils.js';
+export function registerDocsTools(mcp) {
+    mcp.tool('fw_docs', 'Browse Flow Weaver documentation and reference guides. Use action="list" to see topics, action="read" to read a topic, action="search" to search across all docs.', {
+        action: z.enum(['list', 'read', 'search']).describe('What to do: list topics, read a topic, or search'),
+        topic: z.string().optional().describe('Topic slug to read (for action="read")'),
+        query: z.string().optional().describe('Search query (for action="search")'),
+        compact: z.boolean().optional().describe('Return compact LLM-friendly version (default: false)'),
+    }, async (args) => {
+        try {
+            switch (args.action) {
+                case 'list': {
+                    const topics = listTopics();
+                    return makeToolResult({
+                        topics: topics.map((t) => ({
+                            slug: t.slug,
+                            name: t.name,
+                            description: t.description,
+                            keywords: t.keywords,
+                        })),
+                    });
+                }
+                case 'read': {
+                    if (!args.topic) {
+                        return makeErrorResult('MISSING_PARAM', 'The "topic" parameter is required for action="read"');
+                    }
+                    const doc = readTopic(args.topic, args.compact ?? false);
+                    if (!doc) {
+                        const available = listTopics().map((t) => t.slug);
+                        return makeErrorResult('TOPIC_NOT_FOUND', `Unknown topic "${args.topic}". Available topics: ${available.join(', ')}`);
+                    }
+                    return makeToolResult({
+                        name: doc.name,
+                        description: doc.description,
+                        content: doc.content,
+                    });
+                }
+                case 'search': {
+                    if (!args.query) {
+                        return makeErrorResult('MISSING_PARAM', 'The "query" parameter is required for action="search"');
+                    }
+                    const results = searchDocs(args.query);
+                    return makeToolResult({
+                        query: args.query,
+                        results: results.slice(0, 20).map((r) => ({
+                            topic: r.topic,
+                            slug: r.slug,
+                            heading: r.heading,
+                            excerpt: r.excerpt,
+                            relevance: r.relevance,
+                        })),
+                    });
+                }
+            }
+        }
+        catch (err) {
+            return makeErrorResult('DOCS_ERROR', `fw_docs failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+}
+//# sourceMappingURL=tools-docs.js.map

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 } } —
@@ -114,7 +116,10 @@ export function registerEditorTools(mcp, connection, buffer) {
         const result = await connection.sendCommand(args.action, {});
         return makeToolResult(unwrapAckResult(result));
     });
-    mcp.tool('fw_execute_workflow', 'Run the current workflow with optional parameters and return the result.', {
+    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. 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()
@@ -132,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);
@@ -152,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/tools-query.js

@@ -128,7 +128,9 @@ export function registerQueryTools(mcp) {
             return makeErrorResult('VALIDATE_ERROR', `fw_validate failed: ${err instanceof Error ? err.message : String(err)}`);
         }
     });
-    mcp.tool('fw_compile', 'Compile a workflow to executable code. Use target=inngest for per-node step.run() durability.', {
+    mcp.tool('fw_compile', 'Compile a workflow to executable code. Only regenerates code inside @flow-weaver-runtime ' +
+        'and @flow-weaver-body marker sections — user code outside markers is preserved. ' +
+        'Set production: true to strip debug instrumentation. Use target=inngest for per-node step.run() durability.', {
         filePath: z.string().describe('Path to the workflow file'),
         write: z.boolean().optional().describe('Whether to write the output file (default: true)'),
         production: z

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

package/dist/mcp/workflow-executor.js

@@ -5,6 +5,7 @@
 import * as path from 'path';
 import * as fs from 'fs';
 import * as os from 'os';
+import { pathToFileURL } from 'url';
 import ts from 'typescript';
 import { compileWorkflow } from '../api/index.js';
 import { getAvailableWorkflows } from '../api/workflow-file-operations.js';
@@ -81,8 +82,21 @@ export async function executeWorkflowFromFile(filePath, params, options) {
         if (options?.mocks) {
             globalThis.__fw_mocks__ = options.mocks;
         }
-        // Dynamic import (tsx runtime supports .ts imports)
-        const mod = await import(tmpFile);
+        // Set agent channel for waitForAgent pause/resume
+        if (options?.agentChannel) {
+            globalThis.__fw_agent_channel__ = options.agentChannel;
+        }
+        // Dynamic import using file:// URL for cross-platform compatibility
+        // (Windows paths like C:\... break with bare import() — "Received protocol 'c:'")
+        const mod = await import(pathToFileURL(tmpFile).href);
+        // Register exported functions for local invokeWorkflow resolution
+        const workflowRegistry = {};
+        for (const [key, value] of Object.entries(mod)) {
+            if (typeof value === 'function' && key !== '__esModule') {
+                workflowRegistry[key] = value;
+            }
+        }
+        globalThis.__fw_workflow_registry__ = workflowRegistry;
         // Find the target exported function
         const exportedFn = findExportedFunction(mod, options?.workflowName);
         if (!exportedFn) {
@@ -97,13 +111,15 @@ export async function executeWorkflowFromFile(filePath, params, options) {
             result,
             functionName: exportedFn.name,
             executionTime,
-            ...(includeTrace && { trace }),
+            ...(includeTrace && { trace, summary: computeTraceSummary(trace) }),
         };
     }
     finally {
         // Clean up globals
         delete globalThis.__fw_debugger__;
         delete globalThis.__fw_mocks__;
+        delete globalThis.__fw_workflow_registry__;
+        delete globalThis.__fw_agent_channel__;
         // Clean up temp files
         try {
             fs.unlinkSync(tmpFile);
@@ -115,6 +131,53 @@ export async function executeWorkflowFromFile(filePath, params, options) {
         catch { /* ignore */ }
     }
 }
+/** Compute a concise summary from raw trace events. */
+export function computeTraceSummary(trace) {
+    if (trace.length === 0) {
+        return { totalNodes: 0, succeeded: 0, failed: 0, cancelled: 0, nodeTimings: [], totalDurationMs: 0 };
+    }
+    const nodeStartTimes = new Map();
+    const nodeFinalStatus = new Map();
+    const nodeTimings = [];
+    for (const event of trace) {
+        if (event.type !== 'STATUS_CHANGED' || !event.data)
+            continue;
+        const id = event.data.id;
+        const status = event.data.status;
+        if (!id || !status)
+            continue;
+        if (status === 'RUNNING') {
+            nodeStartTimes.set(id, event.timestamp);
+        }
+        if (status === 'SUCCEEDED' || status === 'FAILED' || status === 'CANCELLED') {
+            nodeFinalStatus.set(id, status);
+            const startTime = nodeStartTimes.get(id);
+            if (startTime !== undefined) {
+                nodeTimings.push({ nodeId: id, durationMs: event.timestamp - startTime });
+            }
+        }
+    }
+    let succeeded = 0;
+    let failed = 0;
+    let cancelled = 0;
+    for (const status of nodeFinalStatus.values()) {
+        if (status === 'SUCCEEDED')
+            succeeded++;
+        else if (status === 'FAILED')
+            failed++;
+        else if (status === 'CANCELLED')
+            cancelled++;
+    }
+    const totalDurationMs = trace[trace.length - 1].timestamp - trace[0].timestamp;
+    return {
+        totalNodes: nodeFinalStatus.size,
+        succeeded,
+        failed,
+        cancelled,
+        nodeTimings,
+        totalDurationMs,
+    };
+}
 function findExportedFunction(mod, preferredName) {
     // If a preferred name is specified, try it first
     if (preferredName && typeof mod[preferredName] === 'function') {

package/dist/parser.d.ts

@@ -135,6 +135,14 @@ export declare class AnnotationParser {
      * Processes all paths together for shared deduplication.
      */
     private expandPathMacros;
+    /**
+     * Expand @fanOut macros into 1-to-N connections.
+     */
+    private expandFanOutMacros;
+    /**
+     * Expand @fanIn macros into N-to-1 connections.
+     */
+    private expandFanInMacros;
     /**
      * Generate automatic connections for @autoConnect workflows.
      * Wires nodes in declaration order as a linear pipeline: