@elastic.io/mcp 1.0.0

package/dist/tools/handlers/flow.js

@@ -0,0 +1,899 @@
+import { deserializeJsonApi, deserializeWithMeta } from '../../api/jsonapi.js';
+import { logger } from '../../api/logger.js';
+import { textResult, paginatedResult, formatResult } from '../helpers.js';
+import { validateFlowGraph, checkDiscoveryState, checkFlowLifecycle, checkFlowBuildingGuideRead, healthCheckFlow, formatHealthCheck } from '../validation.js';
+import { PLACEHOLDER_VALUES, PLACEHOLDER_DEFAULT, COMPONENT_SAMPLE_SCHEMAS, PAGE_SIZE } from '../constants.js';
+/**
+ * Full domino-effect impact analysis for flow graph changes.
+ * Compares existing flow/draft graph with new body and returns a formatted
+ * impact report, or null if there are no changes to report.
+ */
+export function analyzeFlowImpact(existingFlow, body, newNodes) {
+    if (!existingFlow?.graph)
+        return null;
+    const impactLines = [];
+    const prevNodes = existingFlow.graph.nodes || [];
+    const prevEdges = existingFlow.graph.edges || [];
+    const updatedNodes = newNodes || body?.data?.attributes?.graph?.nodes || [];
+    const newEdges = body?.data?.attributes?.graph?.edges || [];
+    if (updatedNodes.length === 0 && newEdges.length === 0)
+        return null;
+    const newNodeIds = new Set(updatedNodes.map((n) => n.id));
+    const prevNodeIds = new Set(prevNodes.map((n) => n.id));
+    const nodeNameById = new Map(updatedNodes.map((n) => [n.id, n.name || n.id]));
+    const prevNodeNameById = new Map(prevNodes.map((n) => [n.id, n.name || n.id]));
+    // Extract all $getPassthrough().step_X references from an object
+    const extractPassthroughRefs = (obj) => {
+        const refs = new Set();
+        const str = JSON.stringify(obj || {});
+        const re = /\$getPassthrough\(\)\.(\w+)\./g;
+        let m;
+        while ((m = re.exec(str)) !== null) {
+            refs.add(m[1]);
+        }
+        return refs;
+    };
+    // Find all steps that reference a given stepId via $getPassthrough()
+    const findStepsReferencingId = (stepId) => {
+        const result = [];
+        for (const edge of newEdges) {
+            if (edge.config) {
+                const refs = extractPassthroughRefs(edge.config);
+                if (refs.has(stepId)) {
+                    const name = nodeNameById.get(edge.target) || edge.target;
+                    if (!result.includes(name))
+                        result.push(name);
+                }
+            }
+        }
+        for (const node of updatedNodes) {
+            if (node.fields) {
+                const refs = extractPassthroughRefs(node.fields);
+                if (refs.has(stepId)) {
+                    const name = nodeNameById.get(node.id) || node.id;
+                    if (!result.includes(name))
+                        result.push(name);
+                }
+            }
+        }
+        return result;
+    };
+    // BFS downstream from a step via edges
+    const getDownstreamChain = (startId) => {
+        const chain = [];
+        const visited = new Set();
+        const queue = [startId];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            for (const edge of newEdges) {
+                if (edge.source === current && !visited.has(edge.target)) {
+                    visited.add(edge.target);
+                    chain.push(nodeNameById.get(edge.target) || edge.target);
+                    queue.push(edge.target);
+                }
+            }
+        }
+        return chain;
+    };
+    // Track all steps whose samples become stale (need refresh via debug_flow_step)
+    const staleSteps = new Set();
+    // 1. Removed nodes
+    for (const prev of prevNodes) {
+        if (!newNodeIds.has(prev.id)) {
+            const hasSamples = prev.selected_data_samples?.length > 0;
+            const referencedBy = findStepsReferencingId(prev.id);
+            let line = `REMOVED: "${prev.name || prev.id}"`;
+            if (hasSamples)
+                line += ` (${prev.selected_data_samples.length} data sample(s) lost)`;
+            if (referencedBy.length > 0) {
+                line += `\n    ⚠ Broken $getPassthrough().${prev.id} references in: ${referencedBy.join(', ')}`;
+                referencedBy.forEach(name => {
+                    const id = updatedNodes.find((n) => (n.name || n.id) === name)?.id;
+                    if (id)
+                        staleSteps.add(id);
+                });
+            }
+            impactLines.push(line);
+        }
+    }
+    // 2. New nodes
+    for (const node of updatedNodes) {
+        if (!prevNodeIds.has(node.id)) {
+            const downstream = getDownstreamChain(node.id);
+            staleSteps.add(node.id);
+            let line = `ADDED: "${node.name || node.id}" — needs data sample via debug_flow_step`;
+            if (downstream.length > 0) {
+                line += `\n    ↳ Downstream steps that depend on this sample: ${downstream.join(' → ')}`;
+                downstream.forEach(name => {
+                    const id = updatedNodes.find((n) => (n.name || n.id) === name)?.id;
+                    if (id)
+                        staleSteps.add(id);
+                });
+            }
+            impactLines.push(line);
+        }
+    }
+    // 3. Changed node fields (output schema may change)
+    for (const node of updatedNodes) {
+        const prev = prevNodes.find((p) => p.id === node.id);
+        if (prev && JSON.stringify(prev.fields) !== JSON.stringify(node.fields)) {
+            const referencedBy = findStepsReferencingId(node.id);
+            const downstream = getDownstreamChain(node.id);
+            staleSteps.add(node.id);
+            let line = `FIELDS CHANGED: "${node.name || node.id}" — output schema may differ, sample becomes stale`;
+            if (referencedBy.length > 0) {
+                line += `\n    ⚠ Steps reading $getPassthrough().${node.id}: ${referencedBy.join(', ')}`;
+            }
+            if (downstream.length > 0) {
+                line += `\n    ↳ Full downstream cascade: ${downstream.join(' → ')}`;
+            }
+            referencedBy.forEach(name => {
+                const id = updatedNodes.find((n) => (n.name || n.id) === name)?.id;
+                if (id)
+                    staleSteps.add(id);
+            });
+            downstream.forEach(name => {
+                const id = updatedNodes.find((n) => (n.name || n.id) === name)?.id;
+                if (id)
+                    staleSteps.add(id);
+            });
+            impactLines.push(line);
+        }
+    }
+    // 4. Changed/new/removed edges
+    const prevEdgeMap = new Map(prevEdges.map((e) => [`${e.source}:${e.target}`, e]));
+    const newEdgeKeys = new Set(newEdges.map((e) => `${e.source}:${e.target}`));
+    for (const edge of newEdges) {
+        const key = `${edge.source}:${edge.target}`;
+        const prev = prevEdgeMap.get(key);
+        const targetName = nodeNameById.get(edge.target) || edge.target;
+        if (!prev) {
+            const downstream = getDownstreamChain(edge.target);
+            let line = `NEW EDGE: ${nodeNameById.get(edge.source) || edge.source} → ${targetName}`;
+            if (edge.config?.condition)
+                line += ` [condition: ${edge.config.condition}]`;
+            if (downstream.length > 0) {
+                line += `\n    ↳ Downstream: ${downstream.join(' → ')}`;
+            }
+            staleSteps.add(edge.target);
+            impactLines.push(line);
+        }
+        else {
+            if (edge.config?.mapper && JSON.stringify(prev.config?.mapper) !== JSON.stringify(edge.config.mapper)) {
+                const downstream = getDownstreamChain(edge.target);
+                staleSteps.add(edge.target);
+                let line = `MAPPER CHANGED: → ${targetName} — receives different input data, sample becomes stale`;
+                if (downstream.length > 0) {
+                    line += `\n    ↳ Downstream cascade: ${downstream.join(' → ')}`;
+                    downstream.forEach(name => {
+                        const id = updatedNodes.find((n) => (n.name || n.id) === name)?.id;
+                        if (id)
+                            staleSteps.add(id);
+                    });
+                }
+                impactLines.push(line);
+            }
+            if (JSON.stringify(prev.config?.condition) !== JSON.stringify(edge.config?.condition)) {
+                let line = `CONDITION CHANGED: → ${targetName}`;
+                line += `\n    was: ${prev.config?.condition || '(none)'}`;
+                line += `\n    now: ${edge.config?.condition || '(none)'}`;
+                impactLines.push(line);
+            }
+        }
+    }
+    // Removed edges
+    for (const prev of prevEdges) {
+        const key = `${prev.source}:${prev.target}`;
+        if (!newEdgeKeys.has(key)) {
+            const sourceName = prevNodeNameById.get(prev.source) || nodeNameById.get(prev.source) || prev.source;
+            const targetName = prevNodeNameById.get(prev.target) || nodeNameById.get(prev.target) || prev.target;
+            impactLines.push(`REMOVED EDGE: ${sourceName} → ${targetName}`);
+        }
+    }
+    // 5. Samples preserved
+    const preservedSteps = updatedNodes.filter((n) => {
+        const prev = prevNodes.find((p) => p.id === n.id);
+        return prev?.selected_data_samples?.length > 0 && n.selected_data_samples?.length > 0 && !staleSteps.has(n.id);
+    });
+    if (preservedSteps.length > 0) {
+        impactLines.push(`\nUNCHANGED: ${preservedSteps.map((n) => `"${n.name || n.id}"`).join(', ')} — samples retained`);
+    }
+    // 6. Summary: steps needing sample refresh
+    const staleStepNames = [...staleSteps]
+        .map(id => nodeNameById.get(id) || id)
+        .filter(Boolean);
+    if (staleStepNames.length > 0) {
+        impactLines.push(`\n⚠ STEPS NEEDING SAMPLE REFRESH (debug_flow_step): ${staleStepNames.join(', ')}`);
+    }
+    if (impactLines.length === 0)
+        return null;
+    return `--- Impact Analysis ---\n${impactLines.join('\n')}`;
+}
+/**
+ * Infer a plausible placeholder value for a field name based on naming conventions.
+ */
+function inferPlaceholderValue(fieldName) {
+    const lower = fieldName.toLowerCase();
+    for (const entry of PLACEHOLDER_VALUES) {
+        if (entry.test(lower)) {
+            return typeof entry.value === 'function' ? entry.value() : entry.value;
+        }
+    }
+    return PLACEHOLDER_DEFAULT;
+}
+/**
+ * Generate a meaningful sample body for a node by analyzing downstream mapper
+ * references and falling back to known component output patterns.
+ */
+function generateSampleBody(node, edges, nodesConfig) {
+    const nodeId = node.id;
+    const command = node.command || '';
+    // Check if nodes_config has explicit sample data for this node
+    const nodeConfig = nodesConfig[nodeId];
+    if (nodeConfig?.sample?.body && Object.keys(nodeConfig.sample.body).length > 0) {
+        return nodeConfig.sample.body;
+    }
+    // Scan all downstream mappers and conditions for references to this node's output.
+    // Track both deep field refs ($getPassthrough().nodeId.body.field) and whole body refs
+    // ($getPassthrough().nodeId.body). For whole body refs, also track the mapper KEY
+    // so we can infer what fields the downstream component expects.
+    const referencedFields = new Set();
+    const wholeBodyMapperKeys = new Set();
+    let hasWholeBodyRef = false;
+    for (const edge of edges) {
+        const mapper = edge.config?.mapper;
+        if (mapper && typeof mapper === 'object' && !Array.isArray(mapper)) {
+            for (const [mapperKey, val] of Object.entries(mapper)) {
+                if (typeof val !== 'string')
+                    continue;
+                // Match $getPassthrough().nodeId.body.field (deep path)
+                const fieldRegex = new RegExp(`\\$getPassthrough\\(\\)\\.${nodeId}\\.body\\.([a-zA-Z_][a-zA-Z0-9_.]*)`, 'g');
+                let match;
+                while ((match = fieldRegex.exec(val)) !== null) {
+                    referencedFields.add(match[1].split('.')[0]);
+                }
+                // Match whole body reference: $getPassthrough().nodeId.body (not followed by .)
+                const wholeBodyRegex = new RegExp(`\\$getPassthrough\\(\\)\\.${nodeId}\\.body(?![.a-zA-Z_])`, 'g');
+                if (wholeBodyRegex.test(val)) {
+                    hasWholeBodyRef = true;
+                    wholeBodyMapperKeys.add(mapperKey);
+                }
+            }
+        }
+        else if (typeof mapper === 'string') {
+            const fieldRegex = new RegExp(`\\$getPassthrough\\(\\)\\.${nodeId}\\.body\\.([a-zA-Z_][a-zA-Z0-9_.]*)`, 'g');
+            let match;
+            while ((match = fieldRegex.exec(mapper)) !== null) {
+                referencedFields.add(match[1].split('.')[0]);
+            }
+            const wholeBodyRegex = new RegExp(`\\$getPassthrough\\(\\)\\.${nodeId}\\.body(?![.a-zA-Z_])`, 'g');
+            if (wholeBodyRegex.test(mapper)) {
+                hasWholeBodyRef = true;
+            }
+        }
+        if (edge.config?.condition && typeof edge.config.condition === 'string') {
+            const cond = edge.config.condition;
+            const fieldRegex = new RegExp(`\\$getPassthrough\\(\\)\\.${nodeId}\\.body\\.([a-zA-Z_][a-zA-Z0-9_.]*)`, 'g');
+            let match;
+            while ((match = fieldRegex.exec(cond)) !== null) {
+                referencedFields.add(match[1].split('.')[0]);
+            }
+        }
+    }
+    // Build sample body from referenced fields
+    const body = {};
+    for (const field of referencedFields) {
+        body[field] = inferPlaceholderValue(field);
+    }
+    // If downstream references the whole body, use the mapper keys as field names
+    // so the UI can render meaningful passthrough pills.
+    // E.g. mapper {"idValue": "$getPassthrough().step_1.body"} → sample {idValue: "sample_value"}
+    if (hasWholeBodyRef) {
+        for (const key of wholeBodyMapperKeys) {
+            if (!body[key]) {
+                body[key] = inferPlaceholderValue(key);
+            }
+        }
+        // Fallback if no keys were captured
+        if (Object.keys(body).length === 0) {
+            body.message = 'Sample data';
+            body.id = 'sample-id-123';
+        }
+    }
+    // If we found referenced fields, return them
+    if (Object.keys(body).length > 0)
+        return body;
+    // Fall back to known component output patterns
+    for (const schema of COMPONENT_SAMPLE_SCHEMAS) {
+        if (schema.pattern.test(command)) {
+            return schema.sample();
+        }
+    }
+    // Generic fallback
+    return { sample: 'auto-generated' };
+}
+const DEBUG_SYNC_TIMEOUT_MS = 30_000;
+/**
+ * Execute a single node via /flows/debug-sync and return the output body.
+ * Returns null on any failure (timeout, bad creds, component error, etc.).
+ */
+async function executeDebugSync(client, workspaceId, node, sampleData) {
+    try {
+        const nodePayload = {
+            id: node.id,
+            command: node.command,
+            fields: node.fields || {}
+        };
+        if (node.credentials_id)
+            nodePayload.credentials_id = node.credentials_id;
+        if (node.secret_id)
+            nodePayload.secret_id = node.secret_id;
+        const payload = {
+            data: {
+                type: 'flow',
+                attributes: {
+                    name: `Debug ${node.command}`,
+                    type: 'debug',
+                    graph: { nodes: [nodePayload], edges: [] }
+                },
+                meta: { sampleData },
+                relationships: {
+                    workspace: { data: { id: workspaceId, type: 'workspace' } }
+                }
+            }
+        };
+        const response = await client.post('/flows/debug-sync', payload, {
+            timeout: DEBUG_SYNC_TIMEOUT_MS,
+            __retryCount: 3 // skip retries — debug-sync 500s are component failures, not transient
+        });
+        const result = response.data?.data?.data || response.data?.data;
+        const body = result?.body;
+        if (body && typeof body === 'object' && Object.keys(body).length > 0) {
+            return body;
+        }
+        logger.warn(`[executeDebugSync] No usable body for ${node.id}, keys=${JSON.stringify(Object.keys(response.data?.data || {}))}`);
+        return null;
+    }
+    catch (err) {
+        logger.warn(`[executeDebugSync] Failed for node ${node.id}: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}
+/**
+ * After creating or updating a flow, automatically create data samples
+ * for nodes that don't already have selected_data_samples.
+ * Attempts debug-sync retrieval only for new nodes (without existing samples),
+ * falls back to synthetic samples on failure.
+ */
+async function autoConfirmSamples(flowId, client, discoveryState) {
+    try {
+        // Get the published flow for workspace info
+        const flowRes = await client.get(`/flows/${flowId}`);
+        const flow = deserializeJsonApi(flowRes.data);
+        const workspaceId = flow?.workspace?.id
+            || flow?.workspace?.data?.id;
+        if (!workspaceId)
+            return;
+        // Get or create the draft
+        let draft;
+        try {
+            const draftRes = await client.get(`/flows/${flowId}/draft`);
+            draft = deserializeJsonApi(draftRes.data);
+        }
+        catch {
+            // Draft doesn't exist yet — create it from the flow's graph
+            const draftAttributes = {
+                name: flow.name || flow.attributes?.name || 'Untitled',
+                graph: flow.graph
+            };
+            if (flow.cron || flow.attributes?.cron) {
+                draftAttributes.cron = flow.cron || flow.attributes.cron;
+            }
+            if (flow.type || flow.attributes?.type) {
+                draftAttributes.type = flow.type || flow.attributes.type;
+            }
+            const createDraftRes = await client.put(`/flows/${flowId}/draft`, {
+                data: {
+                    type: 'flow-draft',
+                    attributes: draftAttributes
+                }
+            });
+            draft = deserializeJsonApi(createDraftRes.data);
+        }
+        // The draft is always the source of truth for graph structure.
+        // autoConfirmSamples only adds missing samples — it never overwrites
+        // the draft's nodes, fields, commands, or edges.
+        const draftNodes = draft?.graph?.nodes || [];
+        if (draftNodes.length === 0)
+            return;
+        let draftUpdated = false;
+        for (const node of draftNodes) {
+            // Skip nodes that already have confirmed samples
+            if (node.selected_data_samples && node.selected_data_samples.length > 0) {
+                continue;
+            }
+            const componentId = node.component_id;
+            if (!componentId)
+                continue;
+            const commandMatch = node.command?.match(/^[^:]+:([^@]+)@/);
+            const method = commandMatch?.[1] || '';
+            if (!method)
+                continue;
+            let versionId = discoveryState.componentVersions.get(componentId);
+            if (!versionId) {
+                try {
+                    const compRes = await client.get(`/components/${componentId}`);
+                    const comp = deserializeJsonApi(compRes.data);
+                    versionId = comp?.latest_version?.id || comp?.latest_version?.data?.id;
+                    if (versionId) {
+                        discoveryState.componentVersions.set(componentId, versionId);
+                    }
+                }
+                catch (err) {
+                    logger.warn(`[autoConfirmSamples] Failed to fetch component ${componentId}: ${err instanceof Error ? err.message : String(err)}`);
+                    continue;
+                }
+            }
+            if (!versionId)
+                continue;
+            // Attempt live retrieval via debug-sync — no synthetic fallback
+            const sampleBody = await executeDebugSync(client, workspaceId, node, {});
+            if (sampleBody) {
+                logger.info(`[autoConfirmSamples] Live sample retrieved for node ${node.id}`);
+            }
+            else {
+                logger.warn(`[autoConfirmSamples] No live sample for node ${node.id} — skipping (use debug_flow_step to retrieve manually)`);
+                continue;
+            }
+            try {
+                const sampleRes = await client.post('/data-samples', {
+                    data: {
+                        type: 'data-sample',
+                        attributes: {
+                            result: { body: sampleBody },
+                            method
+                        },
+                        relationships: {
+                            component: { data: { type: 'component', id: componentId } },
+                            component_version: { data: { type: 'component-version', id: versionId } },
+                            workspace: { data: { type: 'workspace', id: workspaceId } }
+                        }
+                    }
+                });
+                const sample = deserializeJsonApi(sampleRes.data);
+                if (sample?.id) {
+                    node.selected_data_samples = [sample.id];
+                    draftUpdated = true;
+                }
+            }
+            catch (err) {
+                logger.warn(`[autoConfirmSamples] Failed to create sample for node ${node.id}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        if (draftUpdated) {
+            // Always use draft as source of truth — never overwrite draft with published flow data
+            const source = draft;
+            const updateDraftAttributes = {
+                name: source.name || source.attributes?.name || 'Untitled',
+                graph: draft.graph
+            };
+            const cron = source.cron || source.attributes?.cron;
+            if (cron) {
+                updateDraftAttributes.cron = cron;
+            }
+            const type = source.type || source.attributes?.type;
+            if (type) {
+                updateDraftAttributes.type = type;
+            }
+            if (source.description !== undefined) {
+                updateDraftAttributes.description = source.description;
+            }
+            if (source.nodes_config !== undefined) {
+                updateDraftAttributes.nodes_config = source.nodes_config;
+            }
+            await client.put(`/flows/${flowId}/draft`, {
+                data: {
+                    id: draft.id,
+                    type: 'flow-draft',
+                    attributes: updateDraftAttributes
+                }
+            });
+            logger.info(`[autoConfirmSamples] Auto-confirmed synthetic samples for flow ${flowId}`);
+        }
+    }
+    catch (err) {
+        // Non-fatal: flow was created/updated successfully, sample confirmation is best-effort
+        logger.warn(`[autoConfirmSamples] Failed to auto-confirm samples for flow ${flowId}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+export const flowHandlers = {
+    create_flow: async (args, { client, discoveryState }) => {
+        const { body } = args;
+        const guideErrors = checkFlowBuildingGuideRead(discoveryState);
+        if (guideErrors.length > 0) {
+            throw new Error(`Playbook State Machine Check Failed:\n- ${guideErrors.join('\n- ')}`);
+        }
+        const { errors: valErrors, warnings: valWarnings } = validateFlowGraph(body);
+        if (valErrors.length > 0) {
+            throw new Error(`Flow Graph Validation Failed:\n- ${valErrors.join('\n- ')}`);
+        }
+        const stateErrors = checkDiscoveryState(body, discoveryState);
+        if (stateErrors.length > 0) {
+            throw new Error(`Playbook State Machine Check Failed:\n- ${stateErrors.join('\n- ')}`);
+        }
+        // Default cron to every 10 minutes if not specified and flow type is ordinary
+        const attrs = body?.data?.attributes;
+        if (attrs && !attrs.cron && (!attrs.type || attrs.type === 'ordinary')) {
+            attrs.cron = '*/10 * * * *';
+        }
+        const response = await client.post('/flows', body);
+        const data = deserializeJsonApi(response.data);
+        if (data?.id) {
+            await autoConfirmSamples(data.id, client, discoveryState);
+        }
+        // Run health check after creation, merging graph validation warnings
+        const healthCheck = await healthCheckFlow(data, client);
+        healthCheck.warnings.push(...valWarnings);
+        const healthSuffix = formatHealthCheck(healthCheck);
+        const resultText = formatResult(data) + healthSuffix;
+        return { content: [{ type: 'text', text: resultText }] };
+    },
+    get_flow: async (args, { client, discoveryState }) => {
+        const { flowId, include } = args;
+        let url = `/flows/${flowId}`;
+        if (include !== undefined) {
+            url += `?include=${include}`;
+        }
+        const response = await client.get(url);
+        const data = deserializeJsonApi(response.data);
+        discoveryState.inspectedFlows.add(flowId);
+        // Auto-fetch draft if one exists
+        let draft = null;
+        if (data?.draft?.data?.id) {
+            try {
+                const draftRes = await client.get(`/flows/${flowId}/draft`);
+                draft = deserializeJsonApi(draftRes.data);
+            }
+            catch (err) {
+                // Draft link exists but fetch failed — skip silently
+            }
+        }
+        return textResult(draft ? { ...data, draft_content: draft } : data);
+    },
+    get_flow_draft: async (args, { client }) => {
+        const { flowId } = args;
+        const response = await client.get(`/flows/${flowId}/draft`);
+        const data = deserializeJsonApi(response.data);
+        return textResult(data);
+    },
+    list_flows: async (args, { client }) => {
+        const { workspaceId, pageSize, pageNumber, search, status, type, componentId, hasDraft, userId, include, sort } = args;
+        let url = `/flows?workspace_id=${workspaceId}`;
+        const params = [];
+        const limit = pageSize !== undefined ? Math.min(pageSize, PAGE_SIZE.FLOWS_MAX) : PAGE_SIZE.FLOWS_DEFAULT;
+        params.push(`page[size]=${limit}`);
+        if (pageNumber !== undefined)
+            params.push(`page[number]=${pageNumber}`);
+        if (search !== undefined)
+            params.push(`search=${encodeURIComponent(search)}`);
+        if (status !== undefined)
+            params.push(`filter[status]=${status}`);
+        if (type !== undefined)
+            params.push(`filter[type]=${type}`);
+        if (componentId !== undefined)
+            params.push(`filter[component_id]=${componentId}`);
+        if (hasDraft !== undefined)
+            params.push(`filter[has_draft]=${hasDraft}`);
+        if (userId !== undefined)
+            params.push(`filter[user]=${userId}`);
+        if (include !== undefined)
+            params.push(`include=${include}`);
+        if (sort !== undefined)
+            params.push(`sort=${sort}`);
+        if (params.length > 0) {
+            url += `&${params.join('&')}`;
+        }
+        const response = await client.get(url);
+        const { data: rawData, meta } = deserializeWithMeta(response.data);
+        let flowList = Array.isArray(rawData) ? rawData : (rawData ? [rawData] : []);
+        const summary = flowList.map((flow) => ({
+            id: flow.id,
+            name: flow.name,
+            status: flow.status,
+            stepCount: flow.graph?.nodes?.length || 0,
+            triggerComponent: flow.graph?.nodes?.[0]?.component_id || flow.graph?.nodes?.[0]?.component || 'unknown'
+        }));
+        return paginatedResult(summary, meta, limit);
+    },
+    run_flow_now: async (args, { client }) => {
+        const { flowId } = args;
+        const response = await client.post(`/flows/${flowId}/run-now`);
+        const data = deserializeJsonApi(response.data);
+        return textResult(data);
+    },
+    start_flow: async (args, { client }) => {
+        const { flowId } = args;
+        // Pre-start health check
+        const flowRes = await client.get(`/flows/${flowId}`);
+        const flow = deserializeJsonApi(flowRes.data);
+        const healthCheck = await healthCheckFlow(flow, client);
+        if (healthCheck.errors.length > 0) {
+            const healthSuffix = formatHealthCheck(healthCheck);
+            throw new Error(`Flow cannot be started due to configuration issues:${healthSuffix}`);
+        }
+        const response = await client.post(`/flows/${flowId}/start`);
+        const data = deserializeJsonApi(response.data);
+        if (healthCheck.warnings.length > 0) {
+            const healthSuffix = formatHealthCheck(healthCheck);
+            const resultText = formatResult(data) + healthSuffix;
+            return { content: [{ type: 'text', text: resultText }] };
+        }
+        return textResult(data);
+    },
+    stop_flow: async (args, { client }) => {
+        const { flowId } = args;
+        const response = await client.post(`/flows/${flowId}/stop`);
+        const data = deserializeJsonApi(response.data);
+        return textResult(data);
+    },
+    update_flow: async (args, { client, discoveryState }) => {
+        const { flowId, body } = args;
+        const guideErrors = checkFlowBuildingGuideRead(discoveryState);
+        if (guideErrors.length > 0) {
+            throw new Error(`Playbook State Machine Check Failed:\n- ${guideErrors.join('\n- ')}`);
+        }
+        let existingFlow = null;
+        try {
+            const flowRes = await client.get(`/flows/${flowId}`);
+            existingFlow = deserializeJsonApi(flowRes.data);
+        }
+        catch (err) {
+            logger.warn(`Failed to fetch existing flow for validation: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const lifecycleErrors = checkFlowLifecycle(flowId, discoveryState, existingFlow, 'update_flow');
+        if (lifecycleErrors.length > 0) {
+            throw new Error(`Flow Lifecycle Check Failed:\n- ${lifecycleErrors.join('\n- ')}`);
+        }
+        const { errors: valErrors, warnings: valWarnings } = validateFlowGraph(body);
+        if (valErrors.length > 0) {
+            throw new Error(`Flow Graph Validation Failed:\n- ${valErrors.join('\n- ')}`);
+        }
+        const stateErrors = checkDiscoveryState(body, discoveryState, existingFlow);
+        if (stateErrors.length > 0) {
+            throw new Error(`Playbook State Machine Check Failed:\n- ${stateErrors.join('\n- ')}`);
+        }
+        // Full domino-effect impact analysis before publish
+        if (args.confirmed !== true) {
+            const impact = analyzeFlowImpact(existingFlow, body);
+            if (impact) {
+                return {
+                    isError: true,
+                    content: [{
+                            type: 'text',
+                            text: `⚠️ Confirmation required.\n\nAction: Publish (update) flow ${flowId}.\n\n${impact}\n\nTo proceed, call this tool again with the same parameters and set confirmed: true.`
+                        }]
+                };
+            }
+        }
+        const response = await client.patch(`/flows/${flowId}`, body);
+        const data = deserializeJsonApi(response.data);
+        await autoConfirmSamples(flowId, client, discoveryState);
+        // Run health check after update, merging graph validation warnings
+        const healthCheck = await healthCheckFlow(data, client);
+        healthCheck.warnings.push(...valWarnings);
+        const healthSuffix = formatHealthCheck(healthCheck);
+        const resultText = formatResult(data) + healthSuffix;
+        return { content: [{ type: 'text', text: resultText }] };
+    },
+    update_flow_draft: async (args, { client, discoveryState }) => {
+        const { flowId, body } = args;
+        const guideErrors = checkFlowBuildingGuideRead(discoveryState);
+        if (guideErrors.length > 0) {
+            throw new Error(`Playbook State Machine Check Failed:\n- ${guideErrors.join('\n- ')}`);
+        }
+        let existingFlow = null;
+        try {
+            const draftRes = await client.get(`/flows/${flowId}/draft`);
+            existingFlow = deserializeJsonApi(draftRes.data);
+        }
+        catch (err) {
+            try {
+                const flowRes = await client.get(`/flows/${flowId}`);
+                existingFlow = deserializeJsonApi(flowRes.data);
+            }
+            catch (e) {
+                logger.warn(`Failed to fetch existing flow/draft for validation: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+        const lifecycleErrors = checkFlowLifecycle(flowId, discoveryState, existingFlow, 'update_flow_draft');
+        if (lifecycleErrors.length > 0) {
+            throw new Error(`Flow Lifecycle Check Failed:\n- ${lifecycleErrors.join('\n- ')}`);
+        }
+        const { errors: valErrors, warnings: valWarnings } = validateFlowGraph(body);
+        if (valErrors.length > 0) {
+            throw new Error(`Flow Graph Validation Failed:\n- ${valErrors.join('\n- ')}`);
+        }
+        const stateErrors = checkDiscoveryState(body, discoveryState, existingFlow);
+        if (stateErrors.length > 0) {
+            throw new Error(`Playbook State Machine Check Failed:\n- ${stateErrors.join('\n- ')}`);
+        }
+        // Preserve selected_data_samples from existing draft nodes when not explicitly provided
+        const prevNodes = existingFlow?.graph?.nodes || [];
+        const updatedNodes = body?.data?.attributes?.graph?.nodes || [];
+        for (const node of updatedNodes) {
+            if (!node.selected_data_samples) {
+                const prev = prevNodes.find((n) => n.id === node.id);
+                if (prev?.selected_data_samples?.length > 0) {
+                    node.selected_data_samples = prev.selected_data_samples;
+                }
+            }
+        }
+        // Full domino-effect impact analysis
+        if (args.confirmed !== true) {
+            const impact = analyzeFlowImpact(existingFlow, body, updatedNodes);
+            if (impact) {
+                return {
+                    isError: true,
+                    content: [{
+                            type: 'text',
+                            text: `⚠️ Confirmation required.\n\nAction: Update the draft of flow ${flowId}.\n\n${impact}\n\nTo proceed, call this tool again with the same parameters and set confirmed: true.`
+                        }]
+                };
+            }
+        }
+        const response = await client.put(`/flows/${flowId}/draft`, body);
+        const data = deserializeJsonApi(response.data);
+        // Auto-create data samples for steps that don't have them.
+        // Auto-create data samples for steps that don't have them (draft is always source of truth).
+        await autoConfirmSamples(flowId, client, discoveryState);
+        // Detect steps with changed configuration or mappings to remind about data sample updates
+        const changedSteps = [];
+        const existingNodes = existingFlow?.graph?.nodes || [];
+        const existingEdges = existingFlow?.graph?.edges || [];
+        const newNodes = body?.data?.attributes?.graph?.nodes || [];
+        const newEdges = body?.data?.attributes?.graph?.edges || [];
+        const existingNodeMap = new Map(existingNodes.map((n) => [n.id, n]));
+        const existingEdgeMap = new Map(existingEdges.map((e) => [`${e.source}:${e.target}`, e]));
+        for (let i = 0; i < newNodes.length; i++) {
+            const node = newNodes[i];
+            const prev = existingNodeMap.get(node.id);
+            if (!prev || JSON.stringify(prev.fields) !== JSON.stringify(node.fields)) {
+                changedSteps.push(node.name || node.id);
+            }
+        }
+        for (let i = 0; i < newEdges.length; i++) {
+            const edge = newEdges[i];
+            const key = `${edge.source}:${edge.target}`;
+            const prev = existingEdgeMap.get(key);
+            if (edge.config?.mapper && (!prev?.config?.mapper || JSON.stringify(prev.config.mapper) !== JSON.stringify(edge.config.mapper))) {
+                const targetNode = newNodes.find((n) => n.id === edge.target);
+                const stepName = targetNode?.name || edge.target;
+                if (!changedSteps.includes(stepName)) {
+                    changedSteps.push(stepName);
+                }
+            }
+        }
+        let resultText = formatResult(data);
+        if (valWarnings.length > 0) {
+            resultText += '\n\n--- Graph Validation Warnings ---\n' + valWarnings.map(w => `  - ${w}`).join('\n');
+        }
+        if (changedSteps.length > 0) {
+            resultText += '\n\n--- Data Sample Reminder ---\n' +
+                `The following steps had configuration or mapping changes: ${changedSteps.join(', ')}.\n` +
+                'Ask the user if they want to update/regenerate data samples for these steps (using debug_flow_step or create_data_sample).';
+        }
+        return { content: [{ type: 'text', text: resultText }] };
+    },
+    debug_flow_step: async (args, { client, discoveryState }) => {
+        const { workspaceId, command, credentialsId, secretId, fields, sampleData, attachments, stepId: customStepId, flowId, componentId } = args;
+        const stepId = customStepId || 'step_1';
+        const node = {
+            id: stepId,
+            command,
+            error: false
+        };
+        if (fields && Object.keys(fields).length > 0) {
+            node.fields = fields;
+        }
+        if (credentialsId) {
+            node.credentials_id = credentialsId;
+        }
+        if (secretId) {
+            node.secret_id = secretId;
+        }
+        const inputData = sampleData || {};
+        const msgPayload = { body: inputData };
+        if (attachments && Object.keys(attachments).length > 0) {
+            msgPayload.attachments = attachments;
+        }
+        const payload = {
+            data: {
+                type: 'flow',
+                attributes: {
+                    name: `Debug ${command}`,
+                    type: 'debug',
+                    graph: {
+                        nodes: [node],
+                        edges: []
+                    },
+                    variables: {}
+                },
+                meta: {
+                    sampleData: msgPayload
+                },
+                relationships: {
+                    workspace: {
+                        data: {
+                            id: workspaceId,
+                            type: 'workspace'
+                        }
+                    }
+                }
+            }
+        };
+        const response = await client.post('/flows/debug-sync', payload, {
+            __retryCount: 3 // skip retries — debug-sync 500s are component failures, not transient
+        });
+        const result = response.data?.data?.data || response.data?.data || response.data;
+        const body = result?.body;
+        // Save as data sample and update flow draft if flowId and componentId provided
+        if (flowId && componentId && body && typeof body === 'object' && Object.keys(body).length > 0) {
+            try {
+                const commandMatch = command.match(/^[^:]+:([^@]+)@/);
+                const method = commandMatch?.[1] || '';
+                let versionId = discoveryState.componentVersions.get(componentId);
+                if (!versionId) {
+                    const compRes = await client.get(`/components/${componentId}`);
+                    const comp = deserializeJsonApi(compRes.data);
+                    versionId = comp?.latest_version?.id || comp?.latest_version?.data?.id;
+                    if (versionId)
+                        discoveryState.componentVersions.set(componentId, versionId);
+                }
+                if (versionId && method) {
+                    const sampleRes = await client.post('/data-samples', {
+                        data: {
+                            type: 'data-sample',
+                            attributes: {
+                                result: { body },
+                                method
+                            },
+                            relationships: {
+                                component: { data: { type: 'component', id: componentId } },
+                                component_version: { data: { type: 'component-version', id: versionId } },
+                                workspace: { data: { type: 'workspace', id: workspaceId } }
+                            }
+                        }
+                    });
+                    const sample = deserializeJsonApi(sampleRes.data);
+                    if (sample?.id) {
+                        // Update draft with the new sample (append to existing)
+                        const draftRes = await client.get(`/flows/${flowId}/draft`);
+                        const draft = deserializeJsonApi(draftRes.data);
+                        const draftNodes = draft?.graph?.nodes || [];
+                        const targetNode = draftNodes.find((n) => n.id === stepId);
+                        if (targetNode) {
+                            targetNode.selected_data_samples = [sample.id];
+                            const updateAttrs = {
+                                name: draft.name || 'Untitled',
+                                graph: draft.graph
+                            };
+                            if (draft.cron)
+                                updateAttrs.cron = draft.cron;
+                            if (draft.type)
+                                updateAttrs.type = draft.type;
+                            await client.put(`/flows/${flowId}/draft`, {
+                                data: { id: draft.id, type: 'flow-draft', attributes: updateAttrs }
+                            });
+                            logger.info(`[debug_flow_step] Saved sample ${sample.id} for node ${stepId} in flow ${flowId}`);
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                logger.warn(`[debug_flow_step] Failed to save sample for node ${stepId}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        return textResult(result);
+    }
+};
+//# sourceMappingURL=flow.js.map