@fluentcommerce/fluent-mcp-extn 0.1.0

package/dist/workflow-tools.js

@@ -0,0 +1,752 @@
+/**
+ * Workflow management tools: workflow.upload, workflow.diff, workflow.simulate
+ *
+ * Closes the deploy loop — agents can analyze, modify, and deploy
+ * workflow JSON without falling back to CLI.
+ * workflow.simulate adds lightweight static prediction for reasoning about
+ * event outcomes without live execution.
+ */
+import { z } from "zod";
+import { ToolError } from "./errors.js";
+// ---------------------------------------------------------------------------
+// Input schemas
+// ---------------------------------------------------------------------------
+export const WorkflowUploadInputSchema = z.object({
+    workflow: z
+        .union([z.string(), z.record(z.string(), z.unknown())])
+        .describe("Workflow JSON definition (as object or JSON string). Must include name, type, version, statuses, and rulesets."),
+    retailerId: z
+        .string()
+        .optional()
+        .describe("Target retailer ID. Falls back to FLUENT_RETAILER_ID."),
+    validate: z
+        .boolean()
+        .default(true)
+        .describe("Validate workflow structure before uploading (default: true)."),
+    dryRun: z
+        .boolean()
+        .default(false)
+        .describe("If true, validate only without deploying."),
+});
+export const WorkflowDiffInputSchema = z.object({
+    base: z
+        .union([z.string(), z.record(z.string(), z.unknown())])
+        .describe("Base workflow JSON (before changes)"),
+    target: z
+        .union([z.string(), z.record(z.string(), z.unknown())])
+        .describe("Target workflow JSON (after changes)"),
+    format: z
+        .enum(["summary", "detailed", "mermaid"])
+        .default("summary")
+        .describe("Output format: summary (default), detailed, or mermaid"),
+});
+export const WorkflowSimulateInputSchema = z.object({
+    workflow: z
+        .union([z.string(), z.record(z.string(), z.unknown())])
+        .describe("Workflow JSON definition (as object or JSON string)."),
+    currentStatus: z
+        .string()
+        .describe("Current entity status to simulate from (e.g., CREATED, BOOKED)."),
+    eventName: z
+        .string()
+        .optional()
+        .describe("Optional event name to match against ruleset names. If omitted, all rulesets triggered by currentStatus are returned."),
+    entityType: z
+        .string()
+        .optional()
+        .describe("Optional entity type filter for trigger matching."),
+    entitySubtype: z
+        .string()
+        .optional()
+        .describe("Optional entity subtype filter for trigger matching."),
+});
+// ---------------------------------------------------------------------------
+// Tool definitions (JSON Schema for MCP)
+// ---------------------------------------------------------------------------
+export const WORKFLOW_TOOL_DEFINITIONS = [
+    {
+        name: "workflow.upload",
+        description: [
+            "Deploy a workflow JSON definition to the Fluent environment.",
+            "",
+            "Uploads via REST API POST /api/v4.1/workflow/{retailerId} — same endpoint as the CLI.",
+            "",
+            "KEY FEATURES:",
+            "- Structure validation before upload (states, rulesets, triggers)",
+            "- dryRun mode validates without deploying",
+            "- Returns new version number for verification",
+            "- Requires retailerId (from input or FLUENT_RETAILER_ID)",
+            "",
+            "IMPORTANT: For production deployments, prefer 'fluent module install' via CLI",
+            "which bundles workflows with settings, rules, and data in a versioned module.",
+            "Use this tool for interactive editing, hotfixes, or when CLI is unavailable.",
+            "",
+            "VALIDATION checks:",
+            "- name field present",
+            "- At least one status defined",
+            "- All rulesets have name, triggers, and rules (warns if empty)",
+        ].join("\n"),
+        inputSchema: {
+            type: "object",
+            properties: {
+                workflow: {
+                    oneOf: [
+                        { type: "string", description: "Workflow as JSON string" },
+                        {
+                            type: "object",
+                            additionalProperties: true,
+                            description: "Workflow as JSON object",
+                        },
+                    ],
+                    description: "Workflow definition to upload",
+                },
+                retailerId: {
+                    type: "string",
+                    description: "Target retailer ID.",
+                },
+                validate: {
+                    type: "boolean",
+                    description: "Validate structure before uploading (default: true).",
+                },
+                dryRun: {
+                    type: "boolean",
+                    description: "Validate only, do not deploy.",
+                },
+            },
+            required: ["workflow"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "workflow.diff",
+        description: [
+            "Compare two workflow JSON definitions and identify changes.",
+            "",
+            "Pure local computation — no API calls.",
+            "",
+            "Compares: rulesets (added/removed/modified), statuses, triggers, rule props.",
+            "Risk assessment: removing rulesets = HIGH, adding = LOW, modifying props = MEDIUM.",
+            "",
+            "Formats:",
+            "- summary: change counts and risk level",
+            "- detailed: per-ruleset change breakdown",
+            "- mermaid: stateDiagram-v2 with color-coded added/removed/modified states and transitions",
+        ].join("\n"),
+        inputSchema: {
+            type: "object",
+            properties: {
+                base: {
+                    oneOf: [
+                        { type: "string" },
+                        { type: "object", additionalProperties: true },
+                    ],
+                    description: "Base workflow (before)",
+                },
+                target: {
+                    oneOf: [
+                        { type: "string" },
+                        { type: "object", additionalProperties: true },
+                    ],
+                    description: "Target workflow (after)",
+                },
+                format: {
+                    type: "string",
+                    enum: ["summary", "detailed", "mermaid"],
+                    description: "Output format (default: summary)",
+                },
+            },
+            required: ["base", "target"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "workflow.simulate",
+        description: [
+            "Static prediction of workflow event outcomes from workflow JSON.",
+            "",
+            "Pure local computation — no API calls. Parses workflow JSON to find",
+            "matching rulesets and predict state transitions, follow-on events, and",
+            "webhook side effects.",
+            "",
+            "WHAT IT DOES:",
+            "- Finds rulesets whose triggers match the given currentStatus (and optionally eventName)",
+            "- Extracts SetState rules to predict the next status",
+            "- Extracts SendEvent rules to predict follow-on events",
+            "- Extracts SendWebhook rules to identify webhook side effects",
+            "- Identifies custom rules that cannot be statically predicted",
+            "",
+            "IMPORTANT LIMITATIONS (always disclosed in response):",
+            "- STATIC ONLY: Cannot evaluate runtime conditions, entity attributes, or settings values",
+            "- CUSTOM RULES OPAQUE: Java plugin rules (e.g., ForwardIfOrderCoordinatesPresent) may",
+            "  conditionally execute; their behavior cannot be predicted without live state",
+            "- NO CROSS-ENTITY: Does not follow SendEvent chains into child entity workflows",
+            "- Use workflow.transitions for AUTHORITATIVE live validation of available actions",
+            "",
+            "USE CASES:",
+            "- Understand workflow structure before firing events",
+            "- Pre-flight check: 'what rulesets would match if I send event X from status Y?'",
+            "- Documentation: enumerate all possible paths from a given status",
+            "- Debug: 'why did nothing happen?' — check if any rulesets trigger on the status",
+        ].join("\n"),
+        inputSchema: {
+            type: "object",
+            properties: {
+                workflow: {
+                    oneOf: [
+                        { type: "string", description: "Workflow as JSON string" },
+                        {
+                            type: "object",
+                            additionalProperties: true,
+                            description: "Workflow as JSON object",
+                        },
+                    ],
+                    description: "Workflow JSON definition",
+                },
+                currentStatus: {
+                    type: "string",
+                    description: "Current entity status to simulate from (e.g., CREATED, BOOKED)",
+                },
+                eventName: {
+                    type: "string",
+                    description: "Optional event name to match against ruleset names. If omitted, returns all rulesets triggered by currentStatus.",
+                },
+                entityType: {
+                    type: "string",
+                    description: "Optional entity type filter for trigger matching.",
+                },
+                entitySubtype: {
+                    type: "string",
+                    description: "Optional entity subtype filter for trigger matching.",
+                },
+            },
+            required: ["workflow", "currentStatus"],
+            additionalProperties: false,
+        },
+    },
+];
+function parseWorkflow(input) {
+    if (typeof input === "string") {
+        try {
+            return JSON.parse(input);
+        }
+        catch {
+            throw new ToolError("VALIDATION_ERROR", "Invalid JSON string for workflow definition.");
+        }
+    }
+    return input;
+}
+function validateWorkflowStructure(wf) {
+    const errors = [];
+    const warnings = [];
+    // Required top-level fields
+    if (!wf.name || typeof wf.name !== "string") {
+        errors.push("Missing or invalid 'name' field.");
+    }
+    // Check for statuses/subStatuses
+    const statuses = wf.statuses ?? wf.subStatuses;
+    if (!statuses || !Array.isArray(statuses) || statuses.length === 0) {
+        errors.push("Missing or empty 'statuses' array.");
+    }
+    // Check rulesets
+    const rulesets = wf.rulesets;
+    if (!rulesets || !Array.isArray(rulesets)) {
+        errors.push("Missing or invalid 'rulesets' array.");
+    }
+    else {
+        for (let i = 0; i < rulesets.length; i++) {
+            const rs = rulesets[i];
+            if (!rs)
+                continue;
+            if (!rs.name) {
+                errors.push(`Ruleset[${i}]: missing 'name'.`);
+            }
+            const triggers = rs.triggers;
+            if (!triggers || !Array.isArray(triggers) || triggers.length === 0) {
+                warnings.push(`Ruleset[${i}] "${rs.name ?? "unnamed"}": no triggers defined.`);
+            }
+            const rules = rs.rules;
+            if (!rules || !Array.isArray(rules) || rules.length === 0) {
+                warnings.push(`Ruleset[${i}] "${rs.name ?? "unnamed"}": no rules defined.`);
+            }
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}
+function extractRulesetMap(wf) {
+    const rulesets = wf.rulesets;
+    if (!rulesets || !Array.isArray(rulesets))
+        return new Map();
+    const map = new Map();
+    for (const rs of rulesets) {
+        const name = rs.name;
+        if (name)
+            map.set(name, rs);
+    }
+    return map;
+}
+function extractStatuses(wf) {
+    const statuses = (wf.statuses ?? wf.subStatuses);
+    if (!statuses || !Array.isArray(statuses))
+        return new Set();
+    return new Set(statuses
+        .map((s) => (s.name ?? s.status))
+        .filter(Boolean));
+}
+function generateMermaidDiff(base, target, diff) {
+    const lines = ["stateDiagram-v2"];
+    // Styles
+    lines.push("  classDef added fill:#d4edda,stroke:#28a745,color:#155724");
+    lines.push("  classDef removed fill:#f8d7da,stroke:#dc3545,color:#721c24");
+    lines.push("  classDef modified fill:#fff3cd,stroke:#ffc107,color:#856404");
+    // Helper to get transitions from a workflow
+    const getTransitions = (wf) => {
+        const transitions = [];
+        const rulesets = wf.rulesets ?? [];
+        for (const rs of rulesets) {
+            const name = rs.name;
+            const triggers = rs.triggers ?? [];
+            const rules = rs.rules ??
+                [];
+            // Find SetState rules
+            const setStateRules = rules.filter((r) => r.name.includes("SetState") ||
+                r.name.includes("ChangeState") ||
+                r.name.includes("Forward"));
+            for (const trigger of triggers) {
+                if (!trigger.status)
+                    continue;
+                for (const rule of setStateRules) {
+                    if (rule.props?.status) {
+                        transitions.push({
+                            from: trigger.status,
+                            to: rule.props.status,
+                            label: name,
+                        });
+                    }
+                }
+            }
+        }
+        return transitions;
+    };
+    const baseTransitions = getTransitions(base);
+    const targetTransitions = getTransitions(target);
+    // Helper to format transition for set comparison
+    const tKey = (t) => `${t.from}->${t.to}:${t.label}`;
+    const baseSet = new Set(baseTransitions.map(tKey));
+    const targetSet = new Set(targetTransitions.map(tKey));
+    // Render nodes (Statuses)
+    const allStatuses = new Set([
+        ...diff.statuses.added,
+        ...diff.statuses.removed,
+        ...extractStatuses(target),
+    ]);
+    for (const status of allStatuses) {
+        if (diff.statuses.added.includes(status)) {
+            lines.push(`  ${status}:::added`);
+        }
+        else if (diff.statuses.removed.includes(status)) {
+            lines.push(`  ${status}:::removed`);
+        }
+    }
+    // Render edges
+    // 1. Target transitions (Existing + New)
+    for (const t of targetTransitions) {
+        const key = tKey(t);
+        if (!baseSet.has(key)) {
+            lines.push(`  ${t.from} --> ${t.to}: ${t.label} (NEW)`);
+        }
+        else {
+            lines.push(`  ${t.from} --> ${t.to}: ${t.label}`);
+        }
+    }
+    // 2. Removed transitions
+    for (const t of baseTransitions) {
+        const key = tKey(t);
+        if (!targetSet.has(key)) {
+            // Only show removed transition if both nodes still exist or were removed
+            // (Mermaid might error if we link to a non-existent node, but we added all removed statuses above)
+            lines.push(`  ${t.from} --> ${t.to}: ${t.label} (REMOVED)`);
+        }
+    }
+    return lines.join("\n");
+}
+function diffRuleset(base, target) {
+    const diffs = [];
+    // Compare triggers
+    const baseTriggers = JSON.stringify(base.triggers ?? []);
+    const targetTriggers = JSON.stringify(target.triggers ?? []);
+    if (baseTriggers !== targetTriggers) {
+        diffs.push("Triggers modified");
+    }
+    // Compare rules
+    const baseRules = base.rules;
+    const targetRules = target.rules;
+    const baseRuleNames = new Set((baseRules ?? []).map((r) => (r.name ?? r.ruleType)).filter(Boolean));
+    const targetRuleNames = new Set((targetRules ?? []).map((r) => (r.name ?? r.ruleType)).filter(Boolean));
+    for (const name of targetRuleNames) {
+        if (!baseRuleNames.has(name))
+            diffs.push(`Rule added: ${name}`);
+    }
+    for (const name of baseRuleNames) {
+        if (!targetRuleNames.has(name))
+            diffs.push(`Rule removed: ${name}`);
+    }
+    // Compare rule props
+    const baseRuleMap = new Map((baseRules ?? []).map((r) => [
+        (r.name ?? r.ruleType),
+        JSON.stringify(r.props ?? {}),
+    ]));
+    const targetRuleMap = new Map((targetRules ?? []).map((r) => [
+        (r.name ?? r.ruleType),
+        JSON.stringify(r.props ?? {}),
+    ]));
+    for (const [name, baseProps] of baseRuleMap) {
+        const targetProps = targetRuleMap.get(name);
+        if (targetProps && baseProps !== targetProps) {
+            diffs.push(`Rule props modified: ${name}`);
+        }
+    }
+    return diffs;
+}
+function computeWorkflowDiff(base, target) {
+    const baseRulesets = extractRulesetMap(base);
+    const targetRulesets = extractRulesetMap(target);
+    const baseStatuses = extractStatuses(base);
+    const targetStatuses = extractStatuses(target);
+    const added = [];
+    const removed = [];
+    const modified = [];
+    // Find added rulesets
+    for (const [name] of targetRulesets) {
+        if (!baseRulesets.has(name)) {
+            added.push({ name, changeType: "added" });
+        }
+    }
+    // Find removed rulesets
+    for (const [name] of baseRulesets) {
+        if (!targetRulesets.has(name)) {
+            removed.push({ name, changeType: "removed" });
+        }
+    }
+    // Find modified rulesets
+    for (const [name, targetRs] of targetRulesets) {
+        const baseRs = baseRulesets.get(name);
+        if (!baseRs)
+            continue;
+        const details = diffRuleset(baseRs, targetRs);
+        if (details.length > 0) {
+            modified.push({ name, changeType: "modified", details });
+        }
+    }
+    // Status diffs
+    const addedStatuses = [...targetStatuses].filter((s) => !baseStatuses.has(s));
+    const removedStatuses = [...baseStatuses].filter((s) => !targetStatuses.has(s));
+    // Risk assessment
+    let riskLevel = "low";
+    if (removed.length > 0 || removedStatuses.length > 0) {
+        riskLevel = "high";
+    }
+    else if (modified.length > 0) {
+        riskLevel = "medium";
+    }
+    const totalChanges = added.length + removed.length + modified.length;
+    const summary = [
+        `${totalChanges} ruleset change(s): ${added.length} added, ${removed.length} removed, ${modified.length} modified.`,
+        `${addedStatuses.length + removedStatuses.length} status change(s): ${addedStatuses.length} added, ${removedStatuses.length} removed.`,
+        `Risk level: ${riskLevel.toUpperCase()}.`,
+    ].join(" ");
+    return {
+        baseWorkflow: base.name ?? "unknown",
+        targetWorkflow: target.name ?? "unknown",
+        riskLevel,
+        rulesets: { added, removed, modified },
+        statuses: { added: addedStatuses, removed: removedStatuses },
+        summary,
+    };
+}
+function requireWorkflowClient(ctx) {
+    if (!ctx.client) {
+        throw new ToolError("CONFIG_ERROR", "SDK client is not available. Run config.validate and fix auth/base URL.");
+    }
+    return ctx.client;
+}
+/**
+ * Handle workflow.upload tool call.
+ */
+export async function handleWorkflowUpload(args, ctx) {
+    const parsed = WorkflowUploadInputSchema.parse(args);
+    const wf = parseWorkflow(parsed.workflow);
+    // Resolve retailer ID
+    const retailerId = parsed.retailerId ?? ctx.config.retailerId;
+    if (!retailerId) {
+        throw new ToolError("VALIDATION_ERROR", "retailerId is required for workflow upload. Set FLUENT_RETAILER_ID or pass retailerId.");
+    }
+    // Validate if requested
+    if (parsed.validate) {
+        const validation = validateWorkflowStructure(wf);
+        if (!validation.valid) {
+            return {
+                ok: true,
+                valid: false,
+                validationErrors: validation.errors,
+                validationWarnings: validation.warnings,
+                note: "Workflow failed structural validation. Fix errors before uploading.",
+            };
+        }
+        if (parsed.dryRun) {
+            return {
+                ok: true,
+                dryRun: true,
+                valid: true,
+                validationWarnings: validation.warnings.length > 0 ? validation.warnings : undefined,
+                workflowName: wf.name,
+                retailerId,
+                note: "Validation passed. Set dryRun=false to deploy.",
+            };
+        }
+    }
+    else if (parsed.dryRun) {
+        return {
+            ok: true,
+            dryRun: true,
+            validationSkipped: true,
+            workflowName: wf.name,
+            retailerId,
+            note: "Validation skipped. Set dryRun=false to deploy.",
+        };
+    }
+    // Upload via REST API POST /api/v4.1/workflow/{retailerId}
+    // This is the same endpoint the Fluent CLI uses.
+    // NOTE: For production deployments, prefer `fluent module install` via CLI
+    // which bundles workflows with settings, rules, and data in a versioned module.
+    const client = requireWorkflowClient(ctx);
+    // FluentClientAdapter may expose request() for custom REST endpoints
+    const clientAny = client;
+    if (typeof clientAny.request !== "function") {
+        throw new ToolError("CONFIG_ERROR", "SDK client does not expose request() method — cannot call REST workflow upload API. " +
+            "Use the Fluent CLI instead: fluent workflow merge <file> <name> -p <profile> -r <retailer>");
+    }
+    const requestFn = clientAny.request;
+    const response = await requestFn(`/api/v4.1/workflow/${retailerId}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: wf,
+    });
+    return {
+        ok: true,
+        uploaded: true,
+        workflowName: wf.name,
+        retailerId,
+        response,
+        note: "For production deployments, prefer 'fluent module install' via CLI for versioned, bundled deployments.",
+    };
+}
+/**
+ * Handle workflow.diff tool call.
+ * Pure computation — no API calls.
+ */
+export async function handleWorkflowDiff(args, _ctx) {
+    const parsed = WorkflowDiffInputSchema.parse(args);
+    const base = parseWorkflow(parsed.base);
+    const target = parseWorkflow(parsed.target);
+    const diff = computeWorkflowDiff(base, target);
+    if (parsed.format === "detailed") {
+        return {
+            ok: true,
+            diff,
+        };
+    }
+    if (parsed.format === "mermaid") {
+        const diagram = generateMermaidDiff(base, target, diff);
+        return {
+            ok: true,
+            diagram,
+            summary: diff.summary,
+            riskLevel: diff.riskLevel,
+        };
+    }
+    // Summary format (default)
+    return {
+        ok: true,
+        summary: diff.summary,
+        riskLevel: diff.riskLevel,
+        rulesetChanges: {
+            added: diff.rulesets.added.length,
+            removed: diff.rulesets.removed.length,
+            modified: diff.rulesets.modified.length,
+        },
+        statusChanges: {
+            added: diff.statuses.added,
+            removed: diff.statuses.removed,
+        },
+    };
+}
+function classifyRule(rule) {
+    const ruleName = rule.name;
+    const props = rule.props ?? {};
+    // SetState / ChangeState
+    if (/SetState|ChangeState/i.test(ruleName)) {
+        return {
+            name: ruleName,
+            type: "setState",
+            props,
+            prediction: props.status ?? undefined,
+        };
+    }
+    // SendEvent
+    if (/SendEvent/i.test(ruleName)) {
+        return {
+            name: ruleName,
+            type: "sendEvent",
+            props,
+            prediction: props.eventName ?? undefined,
+        };
+    }
+    // SendWebhook
+    if (/SendWebhook|Webhook/i.test(ruleName)) {
+        return {
+            name: ruleName,
+            type: "sendWebhook",
+            props,
+            prediction: props.setting ?? undefined,
+        };
+    }
+    // Everything else is custom/opaque
+    return {
+        name: ruleName,
+        type: "custom",
+        props,
+    };
+}
+function simulateWorkflow(wf, currentStatus, eventName, entityType, entitySubtype) {
+    const rulesets = wf.rulesets;
+    if (!rulesets || !Array.isArray(rulesets))
+        return [];
+    const matches = [];
+    for (const rs of rulesets) {
+        const rsName = rs.name;
+        const triggers = rs.triggers;
+        const rules = rs.rules;
+        if (!rsName || !triggers || !Array.isArray(triggers))
+            continue;
+        // Check each trigger for match
+        for (const trigger of triggers) {
+            const triggerStatus = trigger.status;
+            const triggerEntityType = trigger.entityType;
+            const triggerSubtype = trigger.entitySubtype;
+            // Status must match
+            const statusMatches = triggerStatus === currentStatus;
+            // Event name match: in Fluent, event name must match the ruleset name
+            // When eventName is provided, only matching rulesets pass
+            const eventMatches = !eventName || rsName === eventName || rsName.toLowerCase() === eventName.toLowerCase();
+            // Entity type filter
+            const typeMatches = !entityType || !triggerEntityType || triggerEntityType === entityType;
+            const subtypeMatches = !entitySubtype || !triggerSubtype || triggerSubtype === entitySubtype;
+            if (!statusMatches || !eventMatches || !typeMatches || !subtypeMatches)
+                continue;
+            // Determine match type
+            let matchType;
+            if (statusMatches && eventName && rsName === eventName) {
+                matchType = "statusAndEvent";
+            }
+            else if (statusMatches && !eventName) {
+                matchType = "statusOnly";
+            }
+            else {
+                matchType = eventMatches ? "statusAndEvent" : "statusOnly";
+            }
+            // Classify rules
+            const classifiedRules = (rules ?? []).map(classifyRule);
+            const predictedStatus = classifiedRules.find((r) => r.type === "setState" && r.prediction)
+                ?.prediction ?? null;
+            const predictedEvents = classifiedRules
+                .filter((r) => r.type === "sendEvent" && r.prediction)
+                .map((r) => r.prediction);
+            const predictedWebhooks = classifiedRules
+                .filter((r) => r.type === "sendWebhook" && r.prediction)
+                .map((r) => r.prediction);
+            const customRules = classifiedRules
+                .filter((r) => r.type === "custom")
+                .map((r) => r.name);
+            matches.push({
+                name: rsName,
+                description: rs.description,
+                triggerMatch: trigger,
+                matchType,
+                rules: classifiedRules,
+                predictedStatus,
+                predictedEvents,
+                predictedWebhooks,
+                customRules,
+            });
+            // Only match once per ruleset (first matching trigger)
+            break;
+        }
+    }
+    // Sort: statusAndEvent matches first (most specific)
+    matches.sort((a, b) => {
+        if (a.matchType === "statusAndEvent" && b.matchType !== "statusAndEvent")
+            return -1;
+        if (b.matchType === "statusAndEvent" && a.matchType !== "statusAndEvent")
+            return 1;
+        return 0;
+    });
+    return matches;
+}
+/**
+ * Handle workflow.simulate tool call.
+ * Pure computation — no API calls.
+ */
+export async function handleWorkflowSimulate(args, _ctx) {
+    const parsed = WorkflowSimulateInputSchema.parse(args);
+    const wf = parseWorkflow(parsed.workflow);
+    const matches = simulateWorkflow(wf, parsed.currentStatus, parsed.eventName, parsed.entityType, parsed.entitySubtype);
+    // Collect aggregated predictions
+    const hasCustomRules = matches.some((m) => m.customRules.length > 0);
+    const allCustomRules = [
+        ...new Set(matches.flatMap((m) => m.customRules)),
+    ];
+    const limitations = [
+        "STATIC PREDICTION ONLY — does not account for runtime conditions, entity attributes, or settings values.",
+    ];
+    if (hasCustomRules) {
+        limitations.push(`${allCustomRules.length} custom rule(s) found whose behavior cannot be predicted statically: ${allCustomRules.join(", ")}.`);
+    }
+    limitations.push("Use workflow.transitions for AUTHORITATIVE live validation of available actions.");
+    return {
+        ok: true,
+        workflowName: wf.name ?? "unknown",
+        currentStatus: parsed.currentStatus,
+        eventName: parsed.eventName ?? null,
+        matchedRulesets: matches.length,
+        rulesets: matches.map((m) => ({
+            name: m.name,
+            description: m.description,
+            matchType: m.matchType,
+            predictedStatus: m.predictedStatus,
+            predictedEvents: m.predictedEvents,
+            predictedWebhooks: m.predictedWebhooks,
+            customRules: m.customRules.length > 0 ? m.customRules : undefined,
+            ruleCount: m.rules.length,
+        })),
+        prediction: matches.length > 0
+            ? {
+                likelyNextStatus: matches.find((m) => m.predictedStatus)?.predictedStatus ?? null,
+                followOnEvents: [
+                    ...new Set(matches.flatMap((m) => m.predictedEvents)),
+                ],
+                webhookSideEffects: [
+                    ...new Set(matches.flatMap((m) => m.predictedWebhooks)),
+                ],
+                confidence: hasCustomRules ? "low" : "medium",
+                note: hasCustomRules
+                    ? "Custom rules present — prediction may be incomplete or wrong."
+                    : "No custom rules — prediction is based on standard Fluent rules only.",
+            }
+            : null,
+        limitations,
+    };
+}