@synergenius/flow-weaver 0.33.2 → 0.44.0

package/dist/mcp/tools-debug.js

@@ -1,451 +0,0 @@
-import { z } from 'zod';
-import * as path from 'path';
-import * as fs from 'fs';
-import { parseWorkflow } from '../api/index.js';
-import { getTopologicalOrder } from '../api/query.js';
-import { DebugController } from '../runtime/debug-controller.js';
-import { CheckpointWriter, loadCheckpoint, findLatestCheckpoint } from '../runtime/checkpoint.js';
-import { executeWorkflowFromFile } from './workflow-executor.js';
-import { AgentChannel } from './agent-channel.js';
-import { storeDebugSession, getDebugSession, removeDebugSession, listDebugSessions, } from './debug-session.js';
-import { makeToolResult, makeErrorResult } from './response-utils.js';
-/**
- * Helper: get execution order for a workflow file by parsing its annotations.
- */
-async function getExecutionOrder(filePath, workflowName) {
-    const resolvedPath = path.resolve(filePath);
-    const parsed = await parseWorkflow(resolvedPath, { workflowName });
-    if (parsed.errors.length > 0) {
-        throw new Error(`Failed to parse workflow: ${parsed.errors.join(', ')}`);
-    }
-    return getTopologicalOrder(parsed.ast);
-}
-/**
- * Helper: race execution against debug pause. Returns the outcome.
- */
-async function raceDebugPause(session) {
-    try {
-        const raceResult = await Promise.race([
-            session.executionPromise.then((r) => ({
-                type: 'completed',
-                result: r?.result ?? r,
-            })),
-            session.controller.onPause().then((state) => ({
-                type: 'paused',
-                state,
-            })),
-        ]);
-        if (raceResult.type === 'paused') {
-            session.lastPauseState = raceResult.state;
-        }
-        return raceResult;
-    }
-    catch (err) {
-        return {
-            type: 'error',
-            message: err instanceof Error ? err.message : String(err),
-        };
-    }
-}
-/**
- * Helper: clean up a debug session after completion or abort.
- */
-function cleanupDebugSession(debugId) {
-    const session = getDebugSession(debugId);
-    if (!session)
-        return;
-    for (const tmpFile of session.tmpFiles) {
-        try {
-            fs.unlinkSync(tmpFile);
-        }
-        catch {
-            /* ignore */
-        }
-    }
-    removeDebugSession(debugId);
-}
-/**
- * Helper: find the variable key for a nodeId:portName pair from the variables map.
- * Returns the full key (nodeId:portName:executionIndex) or null.
- */
-function findVariableKey(variables, nodeId, portName, executionIndex) {
-    const prefix = `${nodeId}:${portName}:`;
-    if (executionIndex !== undefined) {
-        const key = `${prefix}${executionIndex}`;
-        return key in variables ? key : null;
-    }
-    // Find the latest execution index for this nodeId:portName
-    let latestKey = null;
-    let latestIndex = -1;
-    for (const key of Object.keys(variables)) {
-        if (key.startsWith(prefix)) {
-            const idx = parseInt(key.substring(prefix.length), 10);
-            if (idx > latestIndex) {
-                latestIndex = idx;
-                latestKey = key;
-            }
-        }
-    }
-    return latestKey;
-}
-export function registerDebugTools(mcp) {
-    // -------------------------------------------------------------------------
-    // fw_debug_workflow — Start a debug session
-    // -------------------------------------------------------------------------
-    mcp.tool('fw_debug_workflow', 'Start a step-through debug session for a workflow. Compiles and executes the workflow, ' +
-        'pausing before the first node. Returns a debugId and the initial pause state.', {
-        filePath: z.string().describe('Path to the workflow .ts file'),
-        workflowName: z.string().optional().describe('Specific workflow function name (for multi-workflow files)'),
-        params: z.record(z.unknown()).optional().describe('Parameters to pass to the workflow'),
-        breakpoints: z.array(z.string()).optional().describe('Node IDs to set as initial breakpoints'),
-        checkpoint: z.boolean().optional().describe('Enable checkpointing to disk after each node (default: false)'),
-    }, async (args) => {
-        try {
-            const debugId = `debug-${Date.now()}-${Math.random().toString(36).slice(2)}`;
-            // Get execution order from the workflow file
-            const executionOrder = await getExecutionOrder(args.filePath, args.workflowName);
-            // Set up checkpoint writer if requested
-            let checkpointWriter;
-            if (args.checkpoint) {
-                checkpointWriter = new CheckpointWriter(args.filePath, args.workflowName ?? 'default', debugId, args.params);
-            }
-            // Create the debug controller
-            const controller = new DebugController({
-                debug: true,
-                checkpoint: args.checkpoint ?? false,
-                checkpointWriter,
-                breakpoints: args.breakpoints,
-                executionOrder,
-            });
-            // Create agent channel in case the workflow uses waitForAgent
-            const agentChannel = new AgentChannel();
-            // Start execution (non-blocking: the workflow will pause at the first node)
-            const execPromise = executeWorkflowFromFile(args.filePath, args.params, {
-                workflowName: args.workflowName,
-                includeTrace: true,
-                agentChannel,
-                debugController: controller,
-            });
-            // Store the session
-            const session = {
-                debugId,
-                filePath: args.filePath,
-                workflowName: args.workflowName,
-                controller,
-                executionPromise: execPromise,
-                createdAt: Date.now(),
-                tmpFiles: [],
-            };
-            storeDebugSession(session);
-            // Wait for the first pause or immediate completion
-            const outcome = await raceDebugPause(session);
-            if (outcome.type === 'paused') {
-                return makeToolResult({
-                    debugId,
-                    status: 'paused',
-                    state: outcome.state,
-                });
-            }
-            if (outcome.type === 'completed') {
-                cleanupDebugSession(debugId);
-                return makeToolResult({
-                    debugId,
-                    status: 'completed',
-                    result: outcome.result,
-                });
-            }
-            // Error
-            cleanupDebugSession(debugId);
-            return makeErrorResult('EXECUTION_ERROR', outcome.message);
-        }
-        catch (err) {
-            return makeErrorResult('DEBUG_START_ERROR', err instanceof Error ? err.message : String(err));
-        }
-    });
-    // -------------------------------------------------------------------------
-    // fw_debug_step — Execute next node then pause
-    // -------------------------------------------------------------------------
-    mcp.tool('fw_debug_step', 'Step to the next node in a debug session. Executes one node then pauses again.', {
-        debugId: z.string().describe('The debug session ID from fw_debug_workflow'),
-    }, async (args) => {
-        const session = getDebugSession(args.debugId);
-        if (!session) {
-            return makeErrorResult('SESSION_NOT_FOUND', `No debug session found with ID "${args.debugId}". Use fw_debug_workflow to start one.`);
-        }
-        try {
-            session.controller.resume({ type: 'step' });
-            const outcome = await raceDebugPause(session);
-            if (outcome.type === 'paused') {
-                return makeToolResult({
-                    status: 'paused',
-                    state: outcome.state,
-                });
-            }
-            if (outcome.type === 'completed') {
-                cleanupDebugSession(args.debugId);
-                return makeToolResult({
-                    status: 'completed',
-                    result: outcome.result,
-                });
-            }
-            cleanupDebugSession(args.debugId);
-            return makeErrorResult('EXECUTION_ERROR', outcome.message);
-        }
-        catch (err) {
-            cleanupDebugSession(args.debugId);
-            return makeErrorResult('STEP_ERROR', err instanceof Error ? err.message : String(err));
-        }
-    });
-    // -------------------------------------------------------------------------
-    // fw_debug_continue — Run to completion or breakpoint
-    // -------------------------------------------------------------------------
-    mcp.tool('fw_debug_continue', 'Continue execution from the current pause point. Runs to completion, or stops at the ' +
-        'next breakpoint if toBreakpoint is true.', {
-        debugId: z.string().describe('The debug session ID'),
-        toBreakpoint: z
-            .boolean()
-            .optional()
-            .describe('If true, pause at the next breakpoint instead of running to completion'),
-    }, async (args) => {
-        const session = getDebugSession(args.debugId);
-        if (!session) {
-            return makeErrorResult('SESSION_NOT_FOUND', `No debug session found with ID "${args.debugId}".`);
-        }
-        try {
-            const action = args.toBreakpoint
-                ? { type: 'continueToBreakpoint' }
-                : { type: 'continue' };
-            session.controller.resume(action);
-            const outcome = await raceDebugPause(session);
-            if (outcome.type === 'paused') {
-                return makeToolResult({
-                    status: 'paused',
-                    state: outcome.state,
-                });
-            }
-            if (outcome.type === 'completed') {
-                cleanupDebugSession(args.debugId);
-                return makeToolResult({
-                    status: 'completed',
-                    result: outcome.result,
-                });
-            }
-            cleanupDebugSession(args.debugId);
-            return makeErrorResult('EXECUTION_ERROR', outcome.message);
-        }
-        catch (err) {
-            cleanupDebugSession(args.debugId);
-            return makeErrorResult('CONTINUE_ERROR', err instanceof Error ? err.message : String(err));
-        }
-    });
-    // -------------------------------------------------------------------------
-    // fw_debug_inspect — Read current state without advancing
-    // -------------------------------------------------------------------------
-    mcp.tool('fw_debug_inspect', 'Inspect the current debug state without advancing execution. Returns all variables, ' +
-        'or filter to a specific node.', {
-        debugId: z.string().describe('The debug session ID'),
-        nodeId: z.string().optional().describe('Filter to show only this node\'s variables'),
-    }, async (args) => {
-        const session = getDebugSession(args.debugId);
-        if (!session) {
-            return makeErrorResult('SESSION_NOT_FOUND', `No debug session found with ID "${args.debugId}".`);
-        }
-        if (!session.lastPauseState) {
-            return makeErrorResult('NOT_PAUSED', 'Debug session has not paused yet. Wait for the workflow to reach a pause point.');
-        }
-        const state = { ...session.lastPauseState };
-        // Filter variables to a specific node if requested
-        if (args.nodeId) {
-            const prefix = `${args.nodeId}:`;
-            const filtered = {};
-            for (const [key, value] of Object.entries(state.variables)) {
-                if (key.startsWith(prefix)) {
-                    // Show as portName:executionIndex for readability
-                    filtered[key.substring(prefix.length)] = value;
-                }
-            }
-            return makeToolResult({
-                nodeId: args.nodeId,
-                variables: filtered,
-                state: {
-                    currentNodeId: state.currentNodeId,
-                    phase: state.phase,
-                    position: state.position,
-                    completedNodes: state.completedNodes,
-                },
-            });
-        }
-        return makeToolResult({ state });
-    });
-    // -------------------------------------------------------------------------
-    // fw_debug_set_variable — Modify a variable value
-    // -------------------------------------------------------------------------
-    mcp.tool('fw_debug_set_variable', 'Modify a variable value in the debug session. The new value will be used by downstream ' +
-        'nodes when execution continues.', {
-        debugId: z.string().describe('The debug session ID'),
-        nodeId: z.string().describe('The node that produced the variable'),
-        portName: z.string().describe('The output port name'),
-        value: z.unknown().describe('The new value to set'),
-        executionIndex: z.number().optional().describe('Execution index (defaults to the latest)'),
-    }, async (args) => {
-        const session = getDebugSession(args.debugId);
-        if (!session) {
-            return makeErrorResult('SESSION_NOT_FOUND', `No debug session found with ID "${args.debugId}".`);
-        }
-        if (!session.lastPauseState) {
-            return makeErrorResult('NOT_PAUSED', 'Cannot modify variables when the session is not paused.');
-        }
-        // Find the variable key
-        const key = findVariableKey(session.lastPauseState.variables, args.nodeId, args.portName, args.executionIndex);
-        if (!key) {
-            return makeErrorResult('VARIABLE_NOT_FOUND', `No variable found for ${args.nodeId}.${args.portName}` +
-                (args.executionIndex !== undefined ? `[${args.executionIndex}]` : '') +
-                '. Check fw_debug_inspect to see available variables.');
-        }
-        // Queue the modification (applied before the next node executes)
-        session.controller.setVariable(key, args.value);
-        // Update the lastPauseState to reflect the modification
-        session.lastPauseState.variables[key] = args.value;
-        return makeToolResult({
-            modified: key,
-            value: args.value,
-        });
-    });
-    // -------------------------------------------------------------------------
-    // fw_debug_breakpoint — Manage breakpoints
-    // -------------------------------------------------------------------------
-    mcp.tool('fw_debug_breakpoint', 'Add, remove, or list breakpoints in a debug session. Breakpoints cause execution to ' +
-        'pause when running with fw_debug_continue(toBreakpoint: true).', {
-        debugId: z.string().describe('The debug session ID'),
-        action: z.enum(['add', 'remove', 'list']).describe('Action to perform'),
-        nodeId: z.string().optional().describe('Node ID for add/remove (not needed for list)'),
-    }, async (args) => {
-        const session = getDebugSession(args.debugId);
-        if (!session) {
-            return makeErrorResult('SESSION_NOT_FOUND', `No debug session found with ID "${args.debugId}".`);
-        }
-        if (args.action === 'add') {
-            if (!args.nodeId) {
-                return makeErrorResult('MISSING_PARAM', 'nodeId is required to add a breakpoint');
-            }
-            session.controller.addBreakpoint(args.nodeId);
-        }
-        else if (args.action === 'remove') {
-            if (!args.nodeId) {
-                return makeErrorResult('MISSING_PARAM', 'nodeId is required to remove a breakpoint');
-            }
-            session.controller.removeBreakpoint(args.nodeId);
-        }
-        return makeToolResult({
-            breakpoints: session.controller.getBreakpoints(),
-        });
-    });
-    // -------------------------------------------------------------------------
-    // fw_resume_from_checkpoint — Resume a crashed workflow
-    // -------------------------------------------------------------------------
-    mcp.tool('fw_resume_from_checkpoint', 'Resume a workflow from a checkpoint file written after a crash. Skips already-completed ' +
-        'nodes and re-runs from the last checkpoint position.', {
-        filePath: z.string().describe('Path to the workflow .ts file'),
-        checkpointFile: z
-            .string()
-            .optional()
-            .describe('Path to the checkpoint file. If omitted, auto-detects the latest.'),
-        workflowName: z
-            .string()
-            .optional()
-            .describe('Workflow function name (for multi-workflow files)'),
-        debug: z
-            .boolean()
-            .optional()
-            .describe('Enter step-through debug mode at the resume point (default: false)'),
-    }, async (args) => {
-        try {
-            // Find checkpoint file
-            const checkpointPath = args.checkpointFile ?? findLatestCheckpoint(args.filePath, args.workflowName);
-            if (!checkpointPath) {
-                return makeErrorResult('NO_CHECKPOINT', `No checkpoint file found for ${args.filePath}. ` +
-                    'Checkpoints are created when running with checkpoint: true.');
-            }
-            // Load and validate checkpoint
-            const { data, stale, rerunNodes, skipNodes } = loadCheckpoint(checkpointPath, args.filePath);
-            const skippedCount = data.completedNodes.length - rerunNodes.length;
-            // Create debug controller with skip nodes from checkpoint
-            const controller = new DebugController({
-                debug: args.debug ?? false,
-                checkpoint: true,
-                checkpointWriter: new CheckpointWriter(args.filePath, data.workflowName, `resume-${Date.now()}`, data.params),
-                executionOrder: data.executionOrder,
-                skipNodes,
-            });
-            const agentChannel = new AgentChannel();
-            // Execute with the skip nodes configured
-            const execPromise = executeWorkflowFromFile(args.filePath, data.params, {
-                workflowName: data.workflowName,
-                includeTrace: true,
-                agentChannel,
-                debugController: controller,
-            });
-            // If debug mode, handle like fw_debug_workflow
-            if (args.debug) {
-                const debugId = `debug-resume-${Date.now()}-${Math.random().toString(36).slice(2)}`;
-                const session = {
-                    debugId,
-                    filePath: args.filePath,
-                    workflowName: data.workflowName,
-                    controller,
-                    executionPromise: execPromise,
-                    createdAt: Date.now(),
-                    tmpFiles: [],
-                };
-                storeDebugSession(session);
-                const outcome = await raceDebugPause(session);
-                if (outcome.type === 'paused') {
-                    return makeToolResult({
-                        debugId,
-                        status: 'paused',
-                        resumedFrom: checkpointPath,
-                        skippedNodes: skippedCount,
-                        ...(rerunNodes.length > 0 && { rerunNodes }),
-                        ...(stale && { warning: 'Workflow file has changed since checkpoint was written.' }),
-                        state: outcome.state,
-                    });
-                }
-                if (outcome.type === 'completed') {
-                    cleanupDebugSession(debugId);
-                    return makeToolResult({
-                        status: 'completed',
-                        resumedFrom: checkpointPath,
-                        skippedNodes: skippedCount,
-                        ...(rerunNodes.length > 0 && { rerunNodes }),
-                        result: outcome.result,
-                    });
-                }
-                cleanupDebugSession(debugId);
-                return makeErrorResult('EXECUTION_ERROR', outcome.message);
-            }
-            // Non-debug mode: run to completion
-            const result = await execPromise;
-            // Clean up the checkpoint file on successful completion
-            const writer = new CheckpointWriter(args.filePath, data.workflowName, '', {});
-            writer.cleanup();
-            return makeToolResult({
-                status: 'completed',
-                resumedFrom: checkpointPath,
-                skippedNodes: skippedCount,
-                ...(rerunNodes.length > 0 && { rerunNodes }),
-                ...(stale && { warning: 'Workflow file has changed since checkpoint was written.' }),
-                result: result?.result ?? result,
-            });
-        }
-        catch (err) {
-            return makeErrorResult('RESUME_ERROR', err instanceof Error ? err.message : String(err));
-        }
-    });
-    // -------------------------------------------------------------------------
-    // fw_list_debug_sessions — List active debug sessions
-    // -------------------------------------------------------------------------
-    mcp.tool('fw_list_debug_sessions', 'List all active debug sessions.', {}, async () => {
-        return makeToolResult(listDebugSessions());
-    });
-}
-//# sourceMappingURL=tools-debug.js.map

package/dist/mcp/tools-diagram.js

@@ -1,97 +0,0 @@
-/**
- * MCP Diagram Tool - fw_diagram
- *
- * Generates diagrams from workflow files or inline source code.
- * Supports SVG, interactive HTML, and ASCII text formats.
- */
-import { z } from 'zod';
-import * as fs from 'fs';
-import * as path from 'path';
-import { fileToSVG, fileToHTML, fileToASCII, sourceToSVG, sourceToHTML, sourceToASCII } from '../diagram/index.js';
-import { makeToolResult, makeErrorResult } from './response-utils.js';
-const ASCII_FORMATS = new Set(['ascii', 'ascii-compact', 'text']);
-export function registerDiagramTools(mcp) {
-    mcp.tool('fw_diagram', 'Generate a diagram of a workflow. Formats: svg/html produce visual markup, ascii/ascii-compact/text produce plain text readable in terminal. ' +
-        'Provide either filePath (workflow .ts file) or source (inline code).', {
-        filePath: z
-            .string()
-            .optional()
-            .describe('Path to the workflow .ts file (required if source is not provided)'),
-        source: z
-            .string()
-            .optional()
-            .describe('Inline workflow source code (required if filePath is not provided)'),
-        outputPath: z
-            .string()
-            .optional()
-            .describe('Output file path. If omitted, returns content as text.'),
-        workflowName: z
-            .string()
-            .optional()
-            .describe('Specific workflow name if file has multiple'),
-        theme: z
-            .enum(['dark', 'light'])
-            .optional()
-            .describe('Color theme (default: dark)'),
-        showPortLabels: z
-            .boolean()
-            .optional()
-            .describe('Show port labels on diagram (default: true)'),
-        format: z
-            .enum(['svg', 'html', 'ascii', 'ascii-compact', 'text'])
-            .optional()
-            .describe('Output format: svg (default), html (interactive viewer), ascii (port-level detail), ascii-compact (compact boxes), text (structured list)'),
-    }, async (args) => {
-        try {
-            if (!args.filePath && !args.source) {
-                return makeErrorResult('MISSING_PARAM', 'Provide either filePath or source parameter');
-            }
-            const format = args.format ?? 'svg';
-            const diagramOptions = {
-                workflowName: args.workflowName,
-                theme: args.theme,
-                showPortLabels: args.showPortLabels,
-                format,
-            };
-            let result;
-            if (args.source) {
-                // Inline source code
-                if (ASCII_FORMATS.has(format)) {
-                    result = sourceToASCII(args.source, diagramOptions);
-                }
-                else if (format === 'html') {
-                    result = sourceToHTML(args.source, diagramOptions);
-                }
-                else {
-                    result = sourceToSVG(args.source, diagramOptions);
-                }
-            }
-            else {
-                // File path
-                const resolvedPath = path.resolve(args.filePath);
-                if (!fs.existsSync(resolvedPath)) {
-                    return makeErrorResult('FILE_NOT_FOUND', `File not found: ${resolvedPath}`);
-                }
-                if (ASCII_FORMATS.has(format)) {
-                    result = fileToASCII(resolvedPath, diagramOptions);
-                }
-                else if (format === 'html') {
-                    result = fileToHTML(resolvedPath, diagramOptions);
-                }
-                else {
-                    result = fileToSVG(resolvedPath, diagramOptions);
-                }
-            }
-            if (args.outputPath) {
-                const outputResolved = path.resolve(args.outputPath);
-                fs.writeFileSync(outputResolved, result, 'utf-8');
-                return makeToolResult({ written: outputResolved, size: result.length });
-            }
-            return makeToolResult(result);
-        }
-        catch (error) {
-            return makeErrorResult('DIAGRAM_ERROR', `Diagram generation failed: ${error instanceof Error ? error.message : String(error)}`);
-        }
-    });
-}
-//# sourceMappingURL=tools-diagram.js.map

package/dist/mcp/tools-docs.js

@@ -1,62 +0,0 @@
-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