@elastic.io/mcp 1.0.1-dev10 → 1.0.1-dev11

package/dist/tools/handlers/flow.js

@@ -1,8 +1,10 @@
+import { inspectFlow, readFlow, saveDraft, publishDraft, validateSample, resampleStaleSteps } from '../flow-build.js';
+import { getFlowBuildStatus, configurationRevision, requireInactive, requireRevision, markRunRequested, schemaErrors } from '../flow-state-machine.js';
+import { fingerprint, operation, schemaFor } from '../flow-evidence.js';
 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';
+import { textResult, paginatedResult } from '../helpers.js';
+import { validateFlowGraph, checkFlowBuildingGuideRead, healthCheckFlow } from '../validation.js';
+import { 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
@@ -209,362 +211,36 @@ export function analyzeFlowImpact(existingFlow, body, newNodes) {
         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
+        if (guideErrors.length)
+            throw new Error(guideErrors.join('\n'));
         const attrs = body?.data?.attributes;
-        if (attrs && !attrs.cron && (!attrs.type || attrs.type === 'ordinary')) {
-            attrs.cron = '*/10 * * * *';
+        if (!attrs || 'graph' in attrs || 'nodes' in attrs || 'edges' in attrs) {
+            throw new Error('create_flow creates an empty flow. Supply minimal attributes without graph; build the draft with update_flow_draft.');
         }
+        if (!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 }] };
+        if (!data?.id)
+            throw new Error('Create returned no flow ID. Inspect existing flows before retrying to avoid a duplicate.');
+        const current = await inspectFlow(client, discoveryState, data.id);
+        return textResult({ ...current.flow, build: await getFlowBuildStatus(discoveryState, data.id) });
     },
     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);
+        const current = await inspectFlow(client, discoveryState, args.flowId);
+        return textResult({ ...current.flow, draft_content: current.draft, build: await getFlowBuildStatus(discoveryState, args.flowId) });
     },
-    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);
+    get_flow_draft: async (args, { client, discoveryState }) => {
+        const current = await inspectFlow(client, discoveryState, args.flowId);
+        return textResult({ draft: current.draft, build: await getFlowBuildStatus(discoveryState, args.flowId) });
+    },
+    get_flow_build_status: async (args, { client, discoveryState }) => {
+        await inspectFlow(client, discoveryState, args.flowId);
+        return textResult(await getFlowBuildStatus(discoveryState, args.flowId));
     },
     list_flows: async (args, { client }) => {
         const { workspaceId, pageSize, pageNumber, search, status, type, componentId, hasDraft, userId, include, sort } = args;
@@ -605,295 +281,147 @@ export const flowHandlers = {
         }));
         return paginatedResult(summary, meta, limit);
     },
-    run_flow_now: async (args, { client }) => {
-        const { flowId } = args;
-        const response = await client.post(`/flows/${flowId}/run-now`);
+    run_flow_now: async (args, { client, discoveryState }) => {
+        const current = await inspectFlow(client, discoveryState, args.flowId);
+        if (current.runtime !== 'ACTIVE')
+            throw new Error('Flow must be ACTIVE before run_flow_now.');
+        const response = await client.post(`/flows/${args.flowId}/run-now`);
         const data = deserializeJsonApi(response.data);
-        return textResult(data);
+        markRunRequested(discoveryState, args.flowId, data?.execution_id || data?.execution?.id);
+        return textResult({ result: data, verification: 'PENDING', message: 'Execution requested. Successful completion has not been verified.' });
     },
-    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);
+    start_flow: async (args, { client, discoveryState }) => {
+        const current = await inspectFlow(client, discoveryState, args.flowId);
+        if (current.runtime === 'ACTIVE')
+            return textResult({ ...current.flow, alreadyActive: true });
+        requireInactive(current);
+        if (current.draft) {
+            const draftGraph = configurationRevision({ graph: current.draft.graph }, false);
+            const flowGraph = configurationRevision({ graph: current.flow.graph }, false);
+            if (draftGraph !== flowGraph) {
+                throw new Error('Unpublished draft changes exist. Publish the validated draft first.');
+            }
+        }
+        const structural = validateFlowGraph({ graph: current.flow.graph });
+        const health = await healthCheckFlow(current.flow, client, discoveryState);
+        const errors = [...structural.errors, ...health.errors];
+        if (errors.length)
+            throw new Error(`Flow cannot be started:\n- ${errors.join('\n- ')}`);
+        const latest = await readFlow(client, args.flowId);
+        requireRevision(latest, current.revision);
+        requireInactive(latest);
+        await client.post(`/flows/${args.flowId}/start`);
+        const started = await inspectFlow(client, discoveryState, args.flowId);
+        return textResult({ ...started.flow, operation: 'start_requested', runtime: started.runtime });
     },
-    stop_flow: async (args, { client }) => {
-        const { flowId } = args;
-        const response = await client.post(`/flows/${flowId}/stop`);
-        const data = deserializeJsonApi(response.data);
-        return textResult(data);
+    stop_flow: async (args, { client, discoveryState }) => {
+        const current = await inspectFlow(client, discoveryState, args.flowId);
+        if (current.runtime === 'INACTIVE')
+            return textResult({ ...current.flow, alreadyInactive: true });
+        if (current.runtime === 'UNKNOWN')
+            throw new Error('Cannot stop flow with unknown runtime status. Inspect again.');
+        if (current.runtime !== 'STOPPING')
+            await client.post(`/flows/${args.flowId}/stop`);
+        const stopped = await inspectFlow(client, discoveryState, args.flowId);
+        return textResult({ ...stopped.flow, operation: 'stop_requested', runtime: stopped.runtime });
     },
     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 (guideErrors.length)
+            throw new Error(guideErrors.join('\n'));
         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 current = await inspectFlow(client, discoveryState, args.flowId);
+            requireRevision(current, args.expectedRevision);
+            return { ...textResult({ preview: analyzeFlowImpact(current.flow, args.body), revision: current.revision,
+                    message: 'Publish the saved draft with confirmed: true and this expectedRevision.' }), isError: 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 }] };
+        return textResult(await publishDraft(client, discoveryState, args));
     },
     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 (guideErrors.length)
+            throw new Error(guideErrors.join('\n'));
         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 current = await inspectFlow(client, discoveryState, args.flowId);
+            requireRevision(current, args.expectedRevision);
+            return { ...textResult({ preview: analyzeFlowImpact(current.draft || current.flow, args.body), revision: current.revision,
+                    message: 'Save the draft with confirmed: true and this expectedRevision.' }), isError: true };
+        }
+        const saved = await saveDraft(client, discoveryState, args);
+        // Impact analysis: compare what was submitted against what existed before.
+        // saveDraft already reconciled the state, so we can compute impact from the
+        // submitted body alone (analyzeFlowImpact only needs the existing graph + body).
+        const result = { ...saved };
+        // Auto-resample steps whose samples were invalidated by the draft change.
+        // Steps with precondition blockers (credentials, metadata) are skipped.
+        const resample = await resampleStaleSteps(client, discoveryState, args.flowId);
+        if (resample.resampled.length || resample.failed.length) {
+            result.resample = resample;
+            result.build = await getFlowBuildStatus(discoveryState, args.flowId);
         }
-        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 }] };
+        return textResult(result);
     },
     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) {
+        const { workspaceId, command, credentialsId, secretId, fields = {}, sampleData, attachments, stepId = 'step_1', flowId, componentId } = args;
+        let current;
+        if (flowId) {
+            current = await inspectFlow(client, discoveryState, flowId);
+            requireRevision(current, args.expectedRevision);
+            requireInactive(current);
+            const node = current.draft?.graph?.nodes?.find((n) => n.id === stepId);
+            if (!node || !componentId)
+                throw new Error('To attach a debug sample, select an existing draft step and its componentId.');
+            const expected = { command: node.command, component_id: node.component_id, fields: node.fields || {},
+                credentials_id: node.credentials_id, secret_id: node.secret_id };
+            const supplied = { command, component_id: componentId, fields, credentials_id: credentialsId, secret_id: secretId };
+            if (current.workspaceId !== workspaceId || fingerprint(expected) !== fingerprint(supplied)) {
+                throw new Error('Debug configuration does not match the current draft step.');
+            }
+            if (current.draft.graph.edges.some((e) => e.target === stepId) && sampleData === undefined) {
+                throw new Error('Provide sampleData from the upstream mapper when debugging an action.');
+            }
+            const inputErrors = schemaErrors(schemaFor(discoveryState, workspaceId, node)?.in, sampleData || {});
+            if (inputErrors.length)
+                throw new Error(`Invalid debug input: ${inputErrors.join('; ')}`);
+        }
+        const node = { id: stepId, command, fields, error: false };
+        if (credentialsId)
             node.credentials_id = credentialsId;
-        }
-        if (secretId) {
+        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 response = await client.post('/flows/debug-sync', { data: {
+                type: 'flow', attributes: { name: `Debug ${command}`, type: 'debug', graph: { nodes: [node], edges: [] }, variables: {} },
+                meta: { sampleData: { body: sampleData || {}, ...(attachments ? { attachments } : {}) } },
+                relationships: { workspace: { data: { id: workspaceId, type: 'workspace' } } },
+            } });
         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) {
+        if (result?.error)
+            return { ...textResult(result), isError: true };
+        if (current && result?.body !== undefined) {
+            const op = operation({ command, component_id: componentId });
+            const sampleResponse = await client.post('/data-samples', { data: {
+                    type: 'data-sample', attributes: { result: { body: result.body }, method: op.method },
+                    relationships: { component: { data: { type: 'component', id: componentId } },
+                        component_version: { data: { type: 'component-version', id: op.version } },
+                        workspace: { data: { type: 'workspace', id: workspaceId } } },
+                } });
+            const sample = deserializeJsonApi(sampleResponse.data);
+            if (!sample?.id)
+                throw new Error('Debug succeeded, but creating its sample returned no ID.');
+            const graph = structuredClone(current.draft.graph);
+            graph.nodes.find((n) => n.id === stepId).selected_data_samples = [sample.id];
             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}`);
-                        }
-                    }
-                }
+                await saveDraft(client, discoveryState, { flowId, expectedRevision: current.revision,
+                    body: { data: { type: 'flow-draft', attributes: { graph } } } });
+                const saved = await inspectFlow(client, discoveryState, flowId);
+                validateSample(discoveryState, flowId, saved, stepId, sample);
+                return textResult({ result, sampleId: sample.id, build: await getFlowBuildStatus(discoveryState, flowId) });
             }
-            catch (err) {
-                logger.warn(`[debug_flow_step] Failed to save sample for node ${stepId}: ${err instanceof Error ? err.message : String(err)}`);
+            catch (error) {
+                throw new Error(`Debug sample ${sample.id} was created, but attachment/validation failed: ${error.message}. Inspect before retrying the debug action.`);
             }
         }
-        return textResult(result);
+        return textResult({ result, sampleSaved: false });
     }
 };
 //# sourceMappingURL=flow.js.map