@mag.ni/process 1.0.0

package/dist/tools/work.js

@@ -0,0 +1,702 @@
+/**
+ * MCP Processes - Work Management Tools
+ * Tools for managing instances, actions, and diagram context
+ */
+import { hasClaimedUser } from "./session.js";
+// =============================================================================
+// Tool Definitions
+// =============================================================================
+/**
+ * Tool: get_my_instances
+ * Get instances assigned to the claimed user
+ */
+export const getMyInstancesTool = {
+    name: "get_my_instances",
+    description: "Get all process instances assigned to you. Each instance is an active run of a user-designed workflow — it tracks your current step, history, and status. Requires an active claim (call claim_user first).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            status: {
+                type: "string",
+                enum: ["active", "completed", "cancelled", "paused"],
+                description: "Optional filter by instance status. If not provided, returns all instances.",
+            },
+        },
+        required: [],
+    },
+};
+/**
+ * Tool: get_instance_details
+ * Get full context for a specific instance
+ */
+export const getInstanceDetailsTool = {
+    name: "get_instance_details",
+    description: "Get the full context for a process instance: current step (with label, description preview, and diagram), step history, and metadata. The step description contains the user's instructions for what to do at this point. Use get_node_details if the description preview is truncated.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            instanceId: {
+                type: "string",
+                description: "ID of the instance to get details for",
+            },
+        },
+        required: ["instanceId"],
+    },
+};
+/**
+ * Tool: get_available_actions
+ * Get actions available at the current step
+ */
+export const getAvailableActionsTool = {
+    name: "get_available_actions",
+    description: "Get the actions available at your current step. At a decision point (diamond node), you choose one path. At a regular step, there is typically one action to proceed. At a parallel split, all paths start simultaneously. Always call this before take_action.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            instanceId: {
+                type: "string",
+                description: "ID of the instance to get available actions for",
+            },
+        },
+        required: ["instanceId"],
+    },
+};
+/**
+ * Tool: take_action
+ * Execute an action on an instance
+ */
+export const takeActionTool = {
+    name: "take_action",
+    description: "Execute an action to advance the process to its next step. Pass the action 'id' from get_available_actions (not the name). The process designer determines what each action leads to — it may advance to the next task, branch at a decision, or complete the workflow.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            instanceId: {
+                type: "string",
+                description: "ID of the instance to take action on",
+            },
+            action: {
+                type: "string",
+                description: "ID of the action to execute (use the 'id' field from get_available_actions)",
+            },
+            data: {
+                type: "object",
+                description: "Optional data payload for the action, if required",
+                additionalProperties: true,
+            },
+        },
+        required: ["instanceId", "action"],
+    },
+};
+/**
+ * Tool: get_diagram_context
+ * Get the full process flow structure
+ */
+export const getDiagramContextTool = {
+    name: "get_diagram_context",
+    description: "Get the complete structure of a process flow: all steps (nodes), connections (edges), and available actions at each step. Use this when you need to understand the full workflow map. Prefer get_node_details for individual steps to reduce context size.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            diagramId: {
+                type: "string",
+                description: "ID of the diagram to get context for",
+            },
+        },
+        required: ["diagramId"],
+    },
+};
+/**
+ * Tool: get_instance_notes
+ * Get all notes for an instance
+ */
+export const getInstanceNotesTool = {
+    name: "get_instance_notes",
+    description: "Get all notes on a process instance. Notes are observations, decisions, or status updates left by agents and users throughout the workflow.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            instanceId: {
+                type: "string",
+                description: "ID of the instance to get notes for",
+            },
+        },
+        required: ["instanceId"],
+    },
+};
+/**
+ * Tool: add_instance_note
+ * Add a note to an instance
+ */
+export const addInstanceNoteTool = {
+    name: "add_instance_note",
+    description: "Add a note to a process instance to report progress, document a decision, or flag an issue. Notes are visible to the user who designed the process and to other agents working on it.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            instanceId: {
+                type: "string",
+                description: "ID of the instance to add the note to",
+            },
+            text: {
+                type: "string",
+                description: "The note text to add",
+            },
+        },
+        required: ["instanceId", "text"],
+    },
+};
+/**
+ * Tool: get_node_details
+ * Get details for specific nodes in a diagram
+ */
+export const getNodeDetailsTool = {
+    name: "get_node_details",
+    description: "Get the full label and description for specific steps (nodes) in a process diagram. Step descriptions contain the user's detailed instructions for what the agent should do. Pass multiple nodeIds in a single call to batch lookups.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            diagramId: {
+                type: "string",
+                description: "ID of the diagram containing the nodes",
+            },
+            nodeIds: {
+                type: "array",
+                items: { type: "string" },
+                description: "Array of node IDs to get details for",
+            },
+        },
+        required: ["diagramId", "nodeIds"],
+    },
+};
+// =============================================================================
+// Constants
+// =============================================================================
+const DESCRIPTION_PREVIEW_LENGTH = 200;
+// =============================================================================
+// Tool Handlers
+// =============================================================================
+/**
+ * Truncate a description to preview length, indicating if truncated
+ */
+function truncateDescription(description) {
+    if (!description) {
+        return { text: null, truncated: false };
+    }
+    if (description.length <= DESCRIPTION_PREVIEW_LENGTH) {
+        return { text: description, truncated: false };
+    }
+    return {
+        text: description.substring(0, DESCRIPTION_PREVIEW_LENGTH) + "...",
+        truncated: true,
+    };
+}
+/**
+ * Handler for get_my_instances tool
+ * Gets instances assigned to the claimed user
+ */
+export async function handleGetMyInstances(client, params) {
+    if (!hasClaimedUser() || !client.hasClaimedUser()) {
+        return JSON.stringify({
+            success: false,
+            error: "No user claimed. Call claim_user first.",
+        }, null, 2);
+    }
+    const instances = await client.getMyInstances(params.status);
+    if (!Array.isArray(instances) || instances.length === 0) {
+        return JSON.stringify({
+            success: true,
+            message: "No instances found for the claimed user",
+            instances: [],
+            filter: params.status || "all",
+        }, null, 2);
+    }
+    // Format instances for display (using backend WorkflowInstanceDto fields)
+    const formattedInstances = instances.map((instance) => ({
+        id: instance.id,
+        customer: instance.customer,
+        currentStep: instance.currentStep,
+        currentDiagramId: instance.currentDiagramId,
+        status: instance.status,
+        startedAt: instance.startedAt,
+        stepEnteredAt: instance.stepEnteredAt,
+    }));
+    return JSON.stringify({
+        success: true,
+        message: `Found ${instances.length} instance(s)`,
+        instances: formattedInstances,
+        filter: params.status || "all",
+    }, null, 2);
+}
+/**
+ * Handler for get_instance_details tool
+ * Gets full context for a specific instance including node labels
+ */
+export async function handleGetInstanceDetails(client, params) {
+    if (!hasClaimedUser() || !client.hasClaimedUser()) {
+        return JSON.stringify({
+            success: false,
+            error: "No user claimed. Call claim_user first.",
+        }, null, 2);
+    }
+    if (!params.instanceId || params.instanceId.trim().length === 0) {
+        return JSON.stringify({
+            success: false,
+            error: "instanceId is required",
+        }, null, 2);
+    }
+    // Get the instance details from backend (returns WorkflowInstanceDto)
+    const instance = await client.getInstanceDetails(params.instanceId.trim());
+    // Fetch diagram to get node labels and descriptions
+    let currentNodeLabel = null;
+    let currentNodeDescription = null;
+    let previousNodeLabel = null;
+    let diagramName = null;
+    const stepHistoryWithLabels = [];
+    try {
+        const diagramId = instance.currentDiagramId;
+        if (diagramId) {
+            const diagram = await client.getDiagram(diagramId);
+            diagramName = diagram.name;
+            // Build a map of node IDs to nodes for quick lookup
+            const nodeMap = new Map();
+            for (const node of diagram.nodes) {
+                nodeMap.set(node.id, node);
+                // Also map by originalId if present
+                if (node.originalId) {
+                    nodeMap.set(node.originalId, node);
+                }
+            }
+            // Get current node info
+            const currentStep = instance.currentStep;
+            const currentNode = nodeMap.get(currentStep);
+            if (currentNode) {
+                currentNodeLabel = currentNode.label || null;
+                currentNodeDescription = currentNode.description || null;
+            }
+            // Get previous node label
+            const previousStep = instance.previousStep;
+            if (previousStep) {
+                const prevNode = nodeMap.get(previousStep);
+                if (prevNode) {
+                    previousNodeLabel = prevNode.label || null;
+                }
+            }
+            // Build step history with labels
+            const stepHistory = instance.stepHistory || [];
+            for (const stepId of stepHistory) {
+                const stepNode = nodeMap.get(stepId);
+                stepHistoryWithLabels.push({
+                    nodeId: stepId,
+                    label: stepNode ? (stepNode.label || null) : null,
+                });
+            }
+        }
+    }
+    catch {
+        // If diagram fetch fails, continue without labels
+    }
+    // Truncate description if too long
+    const descriptionPreview = truncateDescription(currentNodeDescription);
+    // Return the instance data with node labels
+    return JSON.stringify({
+        success: true,
+        instanceId: params.instanceId,
+        instance: {
+            id: instance.id,
+            userId: instance.userId,
+            userName: instance.userName,
+            customer: instance.customer,
+            currentStep: {
+                nodeId: instance.currentStep,
+                label: currentNodeLabel,
+                descriptionPreview: descriptionPreview.text,
+                hasFullDescription: descriptionPreview.truncated,
+            },
+            previousStep: instance.previousStep ? {
+                nodeId: instance.previousStep,
+                label: previousNodeLabel,
+            } : null,
+            currentDiagram: {
+                id: instance.currentDiagramId,
+                name: diagramName,
+            },
+            status: instance.status,
+            startedAt: instance.startedAt,
+            stepEnteredAt: instance.stepEnteredAt,
+            stepHistory: stepHistoryWithLabels,
+            iterationCount: instance.iterationCount,
+            rootInstanceId: instance.rootInstanceId,
+            waitingAtNodeId: instance.waitingAtNodeId,
+            parentNodeId: instance.parentNodeId,
+            parentDiagramId: instance.parentDiagramId,
+            isShadow: instance.isShadow,
+        },
+        hint: descriptionPreview.truncated
+            ? "Use get_node_details to get the full description of the current node"
+            : undefined,
+    }, null, 2);
+}
+/**
+ * Handler for get_available_actions tool
+ * Gets actions available at the current step.
+ * Detects parallel splits (non-diamond nodes with multiple exits) and merges
+ * them into a single action, matching the web interface behavior.
+ */
+export async function handleGetAvailableActions(client, params) {
+    if (!hasClaimedUser() || !client.hasClaimedUser()) {
+        return JSON.stringify({
+            success: false,
+            error: "No user claimed. Call claim_user first.",
+        }, null, 2);
+    }
+    if (!params.instanceId || params.instanceId.trim().length === 0) {
+        return JSON.stringify({
+            success: false,
+            error: "instanceId is required",
+        }, null, 2);
+    }
+    const instanceId = params.instanceId.trim();
+    // Fetch instance to check waiting status and get diagram context
+    let instance = null;
+    try {
+        instance = await client.getInstanceDetails(instanceId);
+    }
+    catch {
+        // Continue without instance details
+    }
+    // Check if instance is waiting at a waitForAll node
+    if (instance?.waitingAtNodeId) {
+        return JSON.stringify({
+            success: true,
+            instanceId,
+            currentNodeId: instance.currentStep,
+            message: "Instance is waiting for all parallel branches to arrive at this node. No actions available until all splits merge.",
+            actions: [],
+            waiting: true,
+        }, null, 2);
+    }
+    const response = await client.getAvailableActions(instanceId);
+    if (response.actions.length === 0) {
+        return JSON.stringify({
+            success: true,
+            instanceId,
+            currentNodeId: response.currentNodeId,
+            message: "No actions available at the current step (may be at an end node)",
+            actions: [],
+        }, null, 2);
+    }
+    // Detect parallel splits by checking the current node's shape in the diagram
+    let isParallelSplit = false;
+    if (response.actions.length > 1 && instance) {
+        try {
+            const diagramId = instance.currentDiagramId;
+            if (diagramId) {
+                const diagram = await client.getDiagram(diagramId);
+                const currentStep = instance.currentStep;
+                // Find the current node and check its shape
+                const nodes = diagram.nodes;
+                const currentNode = nodes.find((n) => n.id === currentStep || n.originalId === currentStep);
+                if (currentNode && currentNode.shape !== "diamond") {
+                    isParallelSplit = true;
+                }
+            }
+        }
+        catch {
+            // If diagram fetch fails, show actions individually
+        }
+    }
+    if (isParallelSplit) {
+        // Merge parallel actions into a single action (matches web interface)
+        // The backend automatically creates split instances for all other paths
+        // when any single action is taken from a parallel split node.
+        const mergedName = response.actions.map((a) => a.name || "proceed").join(" / ");
+        const targetDescriptions = response.actions
+            .map((a) => a.description || a.name || "proceed")
+            .join(", ");
+        return JSON.stringify({
+            success: true,
+            instanceId,
+            currentNodeId: response.currentNodeId,
+            message: "1 action available (parallel split - all paths start simultaneously). IMPORTANT: pass the action 'id' (not 'name') to take_action.",
+            actions: [
+                {
+                    id: response.actions[0].id,
+                    name: mergedName,
+                    description: `Parallel split: starts all paths simultaneously (${targetDescriptions})`,
+                },
+            ],
+        }, null, 2);
+    }
+    // Decision point (diamond) or single action - show individually
+    const formattedActions = response.actions.map((action) => ({
+        id: action.id,
+        name: action.name,
+        description: action.description,
+        targetNodeId: action.targetNodeId,
+        requiresData: action.requiresData,
+        dataSchema: action.dataSchema,
+    }));
+    return JSON.stringify({
+        success: true,
+        instanceId,
+        currentNodeId: response.currentNodeId,
+        message: response.actions.length > 1
+            ? `${response.actions.length} actions available (decision point - choose one)`
+            : "1 action available",
+        actions: formattedActions,
+    }, null, 2);
+}
+/**
+ * Handler for take_action tool
+ * Executes an action on an instance
+ */
+export async function handleTakeAction(client, params) {
+    if (!hasClaimedUser() || !client.hasClaimedUser()) {
+        return JSON.stringify({
+            success: false,
+            error: "No user claimed. Call claim_user first.",
+        }, null, 2);
+    }
+    if (!params.instanceId || params.instanceId.trim().length === 0) {
+        return JSON.stringify({
+            success: false,
+            error: "instanceId is required",
+        }, null, 2);
+    }
+    if (!params.action || params.action.trim().length === 0) {
+        return JSON.stringify({
+            success: false,
+            error: "action is required",
+        }, null, 2);
+    }
+    const response = await client.takeAction(params.instanceId.trim(), {
+        action: params.action.trim(),
+        data: params.data,
+    });
+    return JSON.stringify({
+        success: response.success,
+        message: response.success
+            ? `Action '${params.action}' executed successfully`
+            : "Action failed",
+        result: {
+            instanceId: response.instanceId,
+            action: response.action,
+            previousNodeId: response.previousNodeId,
+            currentNodeId: response.currentNodeId,
+            timestamp: response.timestamp,
+        },
+    }, null, 2);
+}
+/**
+ * Handler for get_diagram_context tool
+ * Gets the full process flow structure
+ */
+export async function handleGetDiagramContext(client, params) {
+    if (!params.diagramId || params.diagramId.trim().length === 0) {
+        return JSON.stringify({
+            success: false,
+            error: "diagramId is required",
+        }, null, 2);
+    }
+    const context = await client.getDiagramContext(params.diagramId.trim());
+    // Convert Map to plain object for JSON serialization
+    const nodeDetailsObj = {};
+    context.nodeDetails.forEach((value, key) => {
+        nodeDetailsObj[key] = {
+            node: {
+                id: value.node.id,
+                type: value.node.type,
+                label: value.node.label,
+                position: value.node.position,
+            },
+            incomingEdges: value.incomingEdges.map((e) => ({
+                id: e.id,
+                sourceNodeId: e.sourceNodeId,
+                label: e.label,
+            })),
+            outgoingEdges: value.outgoingEdges.map((e) => ({
+                id: e.id,
+                targetNodeId: e.targetNodeId,
+                label: e.label,
+                condition: e.condition,
+            })),
+            availableActions: value.availableActions.map((a) => ({
+                id: a.id,
+                name: a.name,
+                description: a.description,
+                targetNodeId: a.targetNodeId,
+            })),
+        };
+    });
+    const diagramNodes = context.diagram.nodes ?? [];
+    const diagramEdges = context.diagram.edges ?? [];
+    return JSON.stringify({
+        success: true,
+        diagram: {
+            id: context.diagram.id,
+            name: context.diagram.name,
+            description: context.diagram.description,
+            nodeCount: diagramNodes.length,
+            edgeCount: diagramEdges.length,
+        },
+        nodes: diagramNodes.map((n) => ({
+            id: n.id,
+            type: n.type,
+            label: n.label,
+            position: n.position,
+        })),
+        edges: diagramEdges.map((e) => ({
+            id: e.id,
+            sourceNodeId: e.sourceNodeId,
+            targetNodeId: e.targetNodeId,
+            label: e.label,
+            condition: e.condition,
+        })),
+        nodeDetails: nodeDetailsObj,
+    }, null, 2);
+}
+/**
+ * Handler for get_instance_notes tool
+ * Gets all notes for an instance
+ */
+export async function handleGetInstanceNotes(client, params) {
+    if (!hasClaimedUser() || !client.hasClaimedUser()) {
+        return JSON.stringify({
+            success: false,
+            error: "No user claimed. Call claim_user first.",
+        }, null, 2);
+    }
+    if (!params.instanceId || params.instanceId.trim().length === 0) {
+        return JSON.stringify({
+            success: false,
+            error: "instanceId is required",
+        }, null, 2);
+    }
+    const response = await client.getInstanceNotes(params.instanceId.trim());
+    const notes = response.notes || [];
+    if (notes.length === 0) {
+        return JSON.stringify({
+            success: true,
+            instanceId: params.instanceId,
+            message: "No notes found for this instance",
+            notes: [],
+        }, null, 2);
+    }
+    // Format notes for display
+    const formattedNotes = notes.map((note) => ({
+        id: note.id,
+        text: note.text,
+        userId: note.userId,
+        userName: note.userName,
+        createdAt: note.createdAt,
+    }));
+    return JSON.stringify({
+        success: true,
+        instanceId: params.instanceId,
+        message: `Found ${notes.length} note(s)`,
+        notes: formattedNotes,
+    }, null, 2);
+}
+/**
+ * Handler for add_instance_note tool
+ * Adds a note to an instance
+ */
+export async function handleAddInstanceNote(client, params) {
+    if (!hasClaimedUser() || !client.hasClaimedUser()) {
+        return JSON.stringify({
+            success: false,
+            error: "No user claimed. Call claim_user first.",
+        }, null, 2);
+    }
+    if (!params.instanceId || params.instanceId.trim().length === 0) {
+        return JSON.stringify({
+            success: false,
+            error: "instanceId is required",
+        }, null, 2);
+    }
+    if (!params.text || params.text.trim().length === 0) {
+        return JSON.stringify({
+            success: false,
+            error: "text is required",
+        }, null, 2);
+    }
+    const note = await client.addInstanceNote(params.instanceId.trim(), params.text.trim());
+    return JSON.stringify({
+        success: true,
+        message: "Note added successfully",
+        note: {
+            id: note.id,
+            text: note.text,
+            userId: note.userId,
+            userName: note.userName,
+            createdAt: note.createdAt,
+        },
+    }, null, 2);
+}
+/**
+ * Handler for get_node_details tool
+ * Gets details for specific nodes in a diagram
+ */
+export async function handleGetNodeDetails(client, params) {
+    if (!params.diagramId || params.diagramId.trim().length === 0) {
+        return JSON.stringify({
+            success: false,
+            error: "diagramId is required",
+        }, null, 2);
+    }
+    if (!params.nodeIds || !Array.isArray(params.nodeIds) || params.nodeIds.length === 0) {
+        return JSON.stringify({
+            success: false,
+            error: "nodeIds is required and must be a non-empty array",
+        }, null, 2);
+    }
+    const diagram = await client.getDiagram(params.diagramId.trim());
+    // Build node map for quick lookup
+    const nodeMap = new Map();
+    for (const node of diagram.nodes) {
+        nodeMap.set(node.id, node);
+        if (node.originalId) {
+            nodeMap.set(node.originalId, node);
+        }
+    }
+    // Get details for requested nodes
+    const nodeDetails = params.nodeIds.map((nodeId) => {
+        const node = nodeMap.get(nodeId.trim());
+        if (!node) {
+            return {
+                nodeId,
+                found: false,
+            };
+        }
+        return {
+            nodeId,
+            found: true,
+            label: node.label || null,
+            description: node.description || null,
+            type: node.type || null,
+        };
+    });
+    const foundCount = nodeDetails.filter((n) => n.found).length;
+    return JSON.stringify({
+        success: true,
+        diagramId: params.diagramId,
+        diagramName: diagram.name,
+        message: `Found ${foundCount} of ${params.nodeIds.length} node(s)`,
+        nodes: nodeDetails,
+    }, null, 2);
+}
+// =============================================================================
+// Exports
+// =============================================================================
+export const workTools = [
+    getMyInstancesTool,
+    getInstanceDetailsTool,
+    getAvailableActionsTool,
+    takeActionTool,
+    getDiagramContextTool,
+    getInstanceNotesTool,
+    addInstanceNoteTool,
+    getNodeDetailsTool,
+];
+//# sourceMappingURL=work.js.map