@components-kit/open-workbook 0.1.4 → 0.1.6

package/assets/mcp-server/dist/index.js

@@ -45,7 +45,7 @@ const STYLE_COPY_TOOL_DIMENSIONS = {
     "excel.style.copy_hidden_rows_columns": "hiddenRowsColumns"
 };
 const runtime = await createRuntimeFacade();
-const runtimeVersion = process.env.OPEN_WORKBOOK_VERSION ?? "0.1.4";
+const runtimeVersion = process.env.OPEN_WORKBOOK_VERSION ?? "0.1.6";
 const server = new McpServer({
     name: "open-workbook",
     version: runtimeVersion
@@ -56,6 +56,7 @@ registerBackupTools(server);
 registerSheetTools(server);
 registerRangeTools(server);
 registerBatchTools(server);
+registerWorkflowTools(server);
 registerPlanTools(server);
 registerTemplateTools(server);
 registerStyleTools(server);
@@ -72,6 +73,7 @@ registerCollaborationTools(server);
 registerLockTools(server);
 registerConflictTools(server);
 registerTransactionTools(server);
+registerJobTools(server);
 registerPermissionsTools(server);
 registerCleanTools(server);
 registerValidateTools(server);
@@ -262,7 +264,7 @@ function registerPrompts(mcp) {
         "1. Locate errors with `excel.formula.find_errors` and `excel.validate.no_formula_errors`.",
         "2. Read formula patterns and dependency graph with `excel.formula.read_patterns`, `excel.formula.get_dependency_graph`, `trace_precedents`, and `trace_dependents`.",
         "3. If a template exists, compare with `excel.formula.validate_against_template`.",
-        "4. Create a repair plan using `excel.formula.repair_patterns`, `fill_down`, `fill_right`, or explicit `range.write_formulas`.",
+        "4. Create a repair plan using `excel.formula.repair_patterns`, `fill_down`, `fill_right`, or explicit `range.write_formulas`; never repair formulas by writing formula strings through `range.write_values`.",
         "5. Preview, apply, recalculate, and re-run formula validation before reporting success."
     ]);
     registerWorkflowPrompt(mcp, "excel.prompts.format_like_template", "Format like template", "Repair styling and layout consistency using registered template fingerprints.", promptArgs, (args) => [
@@ -1066,7 +1068,7 @@ function registerRangeTools(mcp) {
         sheetName: z.string(),
         address: z.string(),
         values: z.array(z.array(z.any()))
-    }, (args) => ({
+    }, "Write constants only through the reversible batch pipeline. Use excel.range.write_formulas for formulas and excel.range.write_number_formats for display formats.", (args) => ({
         kind: "range.write_values",
         workbookId: args.workbookId,
         target: targetFromArgs(args),
@@ -1080,7 +1082,7 @@ function registerRangeTools(mcp) {
         sheetName: z.string(),
         address: z.string(),
         formulas: z.array(z.array(z.string().nullable()))
-    }, (args) => ({
+    }, "Write formulas through the reversible batch pipeline while preserving formats. Use this for cells beginning with = instead of excel.range.write_values.", (args) => ({
         kind: "range.write_formulas",
         workbookId: args.workbookId,
         target: targetFromArgs(args),
@@ -1094,7 +1096,7 @@ function registerRangeTools(mcp) {
         sheetName: z.string(),
         address: z.string(),
         numberFormat: z.array(z.array(z.string()))
-    }, (args) => ({
+    }, "Write number formats through the reversible batch pipeline without changing values or formulas.", (args) => ({
         kind: "range.write_number_formats",
         workbookId: args.workbookId,
         target: targetFromArgs(args),
@@ -1117,6 +1119,35 @@ function registerRangeTools(mcp) {
         destructiveLevel: "format",
         reason: "MCP range write styles"
     }));
+    registerMcpTool(mcp, "excel.range.write_styles_many", {
+        title: "Write many Excel range styles",
+        description: "Apply styles to multiple ranges through one reversible batch transaction. Use this for grouped report styling instead of many parallel write_styles calls.",
+        inputSchema: {
+            workbookId: z.string(),
+            reason: z.string().optional(),
+            entries: z.array(z.object({
+                sheetName: z.string(),
+                address: z.string(),
+                style: z.record(z.string(), z.any()),
+                reason: z.string().optional()
+            })).min(1)
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false }
+    }, async ({ workbookId, reason, entries }) => {
+        const typedWorkbookId = workbookId;
+        const operations = styleEntriesToOperations(typedWorkbookId, entries, reason);
+        const chunkSize = styleBatchChunkSize();
+        if (operations.length > chunkSize) {
+            return jsonResult(runtime.submitChunkedBatch({
+                workbookId: typedWorkbookId,
+                mode: "apply",
+                operations,
+                retryStrategy: "split_style_entries",
+                progressMessage: reason ?? "Apply bulk range styles"
+            }, { goal: reason ?? "Apply bulk range styles", retryStrategy: "split_style_entries" }));
+        }
+        return jsonResult(await runtime.applyBatch({ workbookId: typedWorkbookId, mode: "apply", operations }));
+    });
     for (const name of ["excel.range.clear", "excel.range.clear_values", "excel.range.clear_formats", "excel.range.clear_values_keep_format"]) {
         registerRangeOperation(mcp, name, {
             workbookId: z.string(),
@@ -1204,6 +1235,26 @@ function registerBatchTools(mcp) {
         };
         return jsonResult(await runtime.compileBatch(request));
     });
+    registerMcpTool(mcp, "excel.batch.preflight", {
+        title: "Preflight Excel batch",
+        description: "Estimate batch size and recommend apply, submit, or chunked submit before sending work to Excel.",
+        inputSchema: {
+            workbookId: z.string(),
+            operations: z.array(z.any())
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false
+        }
+    }, async ({ workbookId, operations }) => {
+        const request = {
+            workbookId: workbookId,
+            mode: "validate",
+            operations: operations
+        };
+        return jsonResult(runtime.preflightBatch(request));
+    });
     registerMcpTool(mcp, "excel.batch.dry_run", {
         title: "Dry-run Excel batch",
         description: "Compile a batch and report backups, touched ranges, and estimated changes.",
@@ -1268,6 +1319,601 @@ function registerBatchTools(mcp) {
         }
         return jsonResult(await runtime.applyBatch(request));
     });
+    registerMcpTool(mcp, "excel.batch.submit", {
+        title: "Submit Excel batch",
+        description: "Queue a batch mutation and return transaction progress immediately instead of waiting for Excel execution to finish.",
+        inputSchema: {
+            workbookId: z.string(),
+            operations: z.array(z.any()),
+            confirmationToken: z.string().optional(),
+            expectedTargetFingerprints: z.array(z.any()).optional(),
+            agentId: z.string().optional(),
+            agentName: z.string().optional(),
+            taskId: z.string().optional(),
+            role: z.string().optional()
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            openWorldHint: false
+        }
+    }, async ({ workbookId, operations, confirmationToken, expectedTargetFingerprints, agentId, agentName, taskId, role }) => {
+        const request = {
+            workbookId: workbookId,
+            mode: "apply",
+            operations: operations
+        };
+        if (confirmationToken !== undefined) {
+            request.confirmationToken = confirmationToken;
+        }
+        if (expectedTargetFingerprints !== undefined) {
+            request.expectedTargetFingerprints = expectedTargetFingerprints;
+        }
+        if (agentId !== undefined) {
+            request.agentId = agentId;
+        }
+        if (agentName !== undefined) {
+            request.agentName = agentName;
+        }
+        if (taskId !== undefined) {
+            request.taskId = taskId;
+        }
+        if (role !== undefined) {
+            request.role = role;
+        }
+        return jsonResult(runtime.submitBatch(request));
+    });
+    registerMcpTool(mcp, "excel.batch.submit_chunked", {
+        title: "Submit chunked Excel batch",
+        description: "Preflight a large batch, split safely chunkable operations, queue child transactions, and return one parent job.",
+        inputSchema: {
+            workbookId: z.string(),
+            operations: z.array(z.any()),
+            goal: z.string().optional(),
+            confirmationToken: z.string().optional(),
+            expectedTargetFingerprints: z.array(z.any()).optional(),
+            agentId: z.string().optional(),
+            agentName: z.string().optional(),
+            taskId: z.string().optional(),
+            role: z.string().optional()
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            openWorldHint: false
+        }
+    }, async ({ workbookId, operations, goal, confirmationToken, expectedTargetFingerprints, agentId, agentName, taskId, role }) => {
+        const request = {
+            workbookId: workbookId,
+            mode: "apply",
+            operations: operations
+        };
+        if (goal !== undefined) {
+            request.progressMessage = goal;
+        }
+        if (confirmationToken !== undefined) {
+            request.confirmationToken = confirmationToken;
+        }
+        if (expectedTargetFingerprints !== undefined) {
+            request.expectedTargetFingerprints = expectedTargetFingerprints;
+        }
+        if (agentId !== undefined) {
+            request.agentId = agentId;
+        }
+        if (agentName !== undefined) {
+            request.agentName = agentName;
+        }
+        if (taskId !== undefined) {
+            request.taskId = taskId;
+        }
+        if (role !== undefined) {
+            request.role = role;
+        }
+        return jsonResult(runtime.submitChunkedBatch(request, { goal }));
+    });
+}
+function registerWorkflowTools(mcp) {
+    registerMcpTool(mcp, "excel.workflow.prepare_session", {
+        title: "Prepare Excel workflow session",
+        description: "Run the standard read-only discovery sequence before workbook mutations: runtime status, active context, capabilities, workbook map, and collaboration status.",
+        inputSchema: {
+            workbookId: z.string().optional(),
+            includePreview: z.boolean().optional()
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false
+        }
+    }, async ({ workbookId, includePreview }) => {
+        return jsonResult({
+            ok: true,
+            workflow: "excel.workflow.prepare_session",
+            ...(await workflowPreflight(workbookId, includePreview ?? false))
+        });
+    });
+    registerMcpTool(mcp, "excel.workflow.create_formula_sheet", {
+        title: "Create formula sheet",
+        description: "Create a sheet, write a compact values block, write formulas, apply number formats, and validate formulas in one workflow.",
+        inputSchema: {
+            workbookId: z.string(),
+            sheetName: z.string(),
+            activate: z.boolean().optional(),
+            valuesAddress: z.string(),
+            values: z.array(z.array(z.any())),
+            formulasAddress: z.string(),
+            formulas: z.array(z.array(z.string().nullable())),
+            numberFormatAddress: z.string().optional(),
+            numberFormat: z.array(z.array(z.string())).optional(),
+            validateAddress: z.string().optional()
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            openWorldHint: false
+        }
+    }, async (args) => {
+        const workbookId = args.workbookId;
+        const preflight = await workflowPreflight(workbookId);
+        const createSheet = await applySingleOperation(args.workbookId, {
+            kind: "sheet.create",
+            workbookId,
+            sheetName: args.sheetName,
+            activate: args.activate,
+            destructiveLevel: "structure",
+            reason: "Workflow create formula sheet"
+        });
+        const operations = [
+            {
+                kind: "range.write_values",
+                operationId: makeId("op"),
+                workbookId,
+                target: { workbookId, sheetName: args.sheetName, address: args.valuesAddress },
+                values: args.values,
+                preserveFormats: true,
+                destructiveLevel: "values",
+                reason: "Workflow write formula sheet values"
+            },
+            {
+                kind: "range.write_formulas",
+                operationId: makeId("op"),
+                workbookId,
+                target: { workbookId, sheetName: args.sheetName, address: args.formulasAddress },
+                formulas: args.formulas,
+                preserveFormats: true,
+                destructiveLevel: "values",
+                reason: "Workflow write formula sheet formulas"
+            }
+        ];
+        if (args.numberFormatAddress !== undefined && args.numberFormat !== undefined) {
+            operations.push({
+                kind: "range.write_number_formats",
+                operationId: makeId("op"),
+                workbookId,
+                target: { workbookId, sheetName: args.sheetName, address: args.numberFormatAddress },
+                numberFormat: args.numberFormat,
+                preserveValues: true,
+                destructiveLevel: "format",
+                reason: "Workflow format formula sheet numbers"
+            });
+        }
+        const applyResult = await runtime.applyBatch({ workbookId, mode: "apply", operations });
+        const validation = await runtime.validateFormulas({
+            workbookId,
+            sheetName: args.sheetName,
+            address: args.validateAddress ?? args.formulasAddress
+        });
+        return jsonResult({
+            ok: Boolean(createSheet.ok && applyResult.ok && validation.ok),
+            workflow: "excel.workflow.create_formula_sheet",
+            preflight,
+            createSheet,
+            applyResult,
+            validation,
+            summary: {
+                sheetName: args.sheetName,
+                operationCount: operations.length + 1,
+                transactionId: applyResult.transactionId,
+                backupIds: applyResult.backups,
+                formulaValidationOk: validation.ok,
+                formulaIssueCount: validation.issueCount
+            }
+        });
+    });
+    registerMcpTool(mcp, "excel.workflow.create_template_report", {
+        title: "Create template report",
+        description: "Run the standard template report workflow: create sheet from template, clear/fill declared regions, compare style fingerprints, repair styles, and validate against the template.",
+        inputSchema: {
+            workbookId: z.string(),
+            templateId: z.string(),
+            newSheetName: z.string(),
+            clearDataRegions: z.boolean().optional(),
+            fillRegions: z
+                .array(z.object({
+                address: z.string(),
+                values: z.array(z.array(z.any()))
+            }))
+                .optional()
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            openWorldHint: false
+        }
+    }, async ({ workbookId, templateId, newSheetName, clearDataRegions, fillRegions }) => {
+        const preflight = await workflowPreflight(workbookId);
+        const templateResult = runtime.getTemplate(templateId);
+        if (!templateResult.ok || !("template" in templateResult)) {
+            return jsonResult({ ...templateResult, preflight });
+        }
+        const template = templateResult.template;
+        const createSheet = await applySingleOperation(workbookId, {
+            kind: "template.create_sheet_from_template",
+            workbookId: workbookId,
+            templateId: templateId,
+            newSheetName,
+            clearDataRegions: clearDataRegions ?? true,
+            destructiveLevel: "structure",
+            reason: "MCP workflow create template report"
+        });
+        const clearOperations = (clearDataRegions === false ? [] : template.dataRegions).map((address) => ({
+            kind: "range.clear_values_keep_format",
+            operationId: makeId("op"),
+            workbookId: workbookId,
+            destructiveLevel: "values",
+            reason: `Workflow clear data region from template ${templateId}`,
+            target: {
+                workbookId: workbookId,
+                sheetName: newSheetName,
+                address
+            }
+        }));
+        const clearResult = clearOperations.length > 0
+            ? await runtime.applyBatch({ workbookId: workbookId, mode: "apply", operations: clearOperations })
+            : { ok: true, skipped: true };
+        const fillOperations = (fillRegions ?? []).map((region) => ({
+            kind: "range.write_values",
+            operationId: makeId("op"),
+            workbookId: workbookId,
+            destructiveLevel: "values",
+            reason: "Workflow fill template region",
+            target: {
+                workbookId: workbookId,
+                sheetName: newSheetName,
+                address: region.address
+            },
+            values: region.values,
+            preserveFormats: true
+        }));
+        const fillResult = fillOperations.length > 0
+            ? await runtime.applyBatch({ workbookId: workbookId, mode: "apply", operations: fillOperations })
+            : { ok: true, skipped: true };
+        const styleCompare = await runtime.compareStyleFingerprints({
+            workbookId: workbookId,
+            sourceSheetName: template.sourceSheetName,
+            targetSheetName: newSheetName
+        });
+        const styleRepair = await repairTemplateFromArgs({
+            workbookId,
+            templateId,
+            targetSheetName: newSheetName,
+            repair: ["styles"]
+        });
+        const validation = await runtime.validateSheetAgainstTemplate({
+            workbookId: workbookId,
+            templateId: templateId,
+            targetSheetName: newSheetName
+        });
+        return jsonResult({
+            ok: Boolean(createSheet.ok && clearResult.ok && fillResult.ok && validation.ok),
+            workflow: "excel.workflow.create_template_report",
+            preflight,
+            templateId,
+            sourceSheetName: template.sourceSheetName,
+            targetSheetName: newSheetName,
+            createSheet,
+            clearResult,
+            fillResult,
+            styleCompare,
+            styleRepair,
+            validation,
+            summary: {
+                targetSheetName: newSheetName,
+                clearedRegionCount: clearOperations.length,
+                filledRegionCount: fillOperations.length,
+                styleCompared: Boolean(styleCompare.ok),
+                styleRepairAttempted: true,
+                validated: Boolean(validation.ok)
+            }
+        });
+    });
+    registerMcpTool(mcp, "excel.workflow.create_pivot_chart_summary", {
+        title: "Create pivot and chart summary",
+        description: "Run the standard PivotTable and chart creation workflow: capability check, PivotTable create, refresh, chart create, chart source update/refresh, and PivotTable source validation.",
+        inputSchema: {
+            workbookId: z.string(),
+            pivotTableName: z.string(),
+            sourceSheetName: z.string().optional(),
+            sourceAddress: z.string().optional(),
+            sourceTableName: z.string().optional(),
+            pivotDestinationSheetName: z.string(),
+            pivotDestinationAddress: z.string(),
+            rowFields: z.array(z.string()).optional(),
+            columnFields: z.array(z.string()).optional(),
+            filterFields: z.array(z.string()).optional(),
+            dataFields: z
+                .array(z.object({
+                sourceFieldName: z.string(),
+                name: z.string().optional(),
+                summarizeBy: z.string().optional(),
+                numberFormat: z.string().optional()
+            }))
+                .optional(),
+            chartSheetName: z.string(),
+            chartName: z.string(),
+            chartSourceAddress: z.string(),
+            chartType: z.string(),
+            chartTitle: z.string().optional(),
+            chartPosition: z.object({ startCell: z.string(), endCell: z.string().optional() }).optional()
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            openWorldHint: false
+        }
+    }, async (args) => {
+        const workbookId = args.workbookId;
+        const preflight = await workflowPreflight(workbookId);
+        const pivotRequest = {
+            workbookId,
+            pivotTableName: args.pivotTableName,
+            destinationSheetName: args.pivotDestinationSheetName,
+            destinationAddress: args.pivotDestinationAddress,
+            refresh: true
+        };
+        if (args.sourceSheetName !== undefined)
+            pivotRequest.sourceSheetName = args.sourceSheetName;
+        if (args.sourceAddress !== undefined)
+            pivotRequest.sourceAddress = args.sourceAddress;
+        if (args.sourceTableName !== undefined)
+            pivotRequest.sourceTableName = args.sourceTableName;
+        if (args.rowFields !== undefined)
+            pivotRequest.rowFields = args.rowFields;
+        if (args.columnFields !== undefined)
+            pivotRequest.columnFields = args.columnFields;
+        if (args.filterFields !== undefined)
+            pivotRequest.filterFields = args.filterFields;
+        if (args.dataFields !== undefined)
+            pivotRequest.dataFields = args.dataFields;
+        const capability = runtime.getPivotCapabilityMatrix(workbookId);
+        const pivotCreate = await runtime.createPivotTable(pivotRequest);
+        const pivotRefresh = await runtime.refreshPivotTable({ workbookId, pivotTableName: args.pivotTableName });
+        const chartCreateRequest = {
+            workbookId,
+            sheetName: args.chartSheetName,
+            chartName: args.chartName,
+            sourceAddress: args.chartSourceAddress,
+            chartType: args.chartType
+        };
+        if (args.chartTitle !== undefined)
+            chartCreateRequest.title = args.chartTitle;
+        if (args.chartPosition !== undefined)
+            chartCreateRequest.position = args.chartPosition;
+        const chartCreate = await runtime.createChart(chartCreateRequest);
+        const chartUpdate = await runtime.updateChartDataSource({
+            workbookId,
+            sheetName: args.chartSheetName,
+            chartName: args.chartName,
+            sourceAddress: args.chartSourceAddress
+        });
+        const chartRefresh = await runtime.refreshChart({ workbookId, sheetName: args.chartSheetName, chartName: args.chartName });
+        const validation = await runtime.validatePivotSource({
+            workbookId,
+            pivotTableName: args.pivotTableName,
+            expectedRowFields: args.rowFields,
+            expectedColumnFields: args.columnFields,
+            expectedFilterFields: args.filterFields,
+            expectedDataFields: Array.isArray(args.dataFields) ? args.dataFields.map((field) => field.sourceFieldName) : undefined,
+            expectedDataFieldSettings: args.dataFields
+        });
+        return jsonResult({
+            ok: Boolean(pivotCreate.ok && pivotRefresh.ok && chartCreate.ok && chartUpdate.ok && validation.ok),
+            workflow: "excel.workflow.create_pivot_chart_summary",
+            preflight,
+            capability,
+            pivotCreate,
+            pivotRefresh,
+            chartCreate,
+            chartUpdate,
+            chartRefresh,
+            validation,
+            summary: {
+                pivotTableName: args.pivotTableName,
+                chartName: args.chartName,
+                refreshed: Boolean(pivotRefresh.ok && chartRefresh.ok),
+                validated: Boolean(validation.ok)
+            }
+        });
+    });
+    registerMcpTool(mcp, "excel.workflow.repair_formula_errors", {
+        title: "Repair formula errors",
+        description: "Run the standard formula repair workflow: preflight, validate/find errors, read formula patterns, inspect dependency graph, repair by filling or writing scoped formulas, and validate again.",
+        inputSchema: {
+            workbookId: z.string(),
+            sheetName: z.string(),
+            errorAddress: z.string(),
+            patternAddress: z.string().optional(),
+            sourceAddress: z.string().optional(),
+            targetAddress: z.string().optional(),
+            direction: z.enum(["down", "right"]).optional(),
+            formulasAddress: z.string().optional(),
+            formulas: z.array(z.array(z.string().nullable())).optional()
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            openWorldHint: false
+        }
+    }, async (args) => {
+        const workbookId = args.workbookId;
+        const sheetName = args.sheetName;
+        const errorAddress = args.errorAddress;
+        const sourceAddress = args.sourceAddress;
+        const targetAddress = (args.targetAddress ?? args.formulasAddress ?? errorAddress);
+        const preflight = await workflowPreflight(workbookId);
+        const beforeValidation = await runtime.validateFormulas({ workbookId, sheetName, address: errorAddress });
+        const patterns = await runtime.readFormulaPatterns({
+            workbookId,
+            sheetName,
+            address: (args.patternAddress ?? sourceAddress ?? errorAddress)
+        });
+        const dependencyGraph = await runtime.getFormulaDependencyGraph({ workbookId, sheetName, address: errorAddress });
+        let repairResult;
+        if (Array.isArray(args.formulas)) {
+            repairResult = await runtime.applyBatch({
+                workbookId,
+                mode: "apply",
+                operations: [
+                    {
+                        kind: "range.write_formulas",
+                        operationId: makeId("op"),
+                        workbookId,
+                        target: { workbookId, sheetName, address: targetAddress },
+                        formulas: args.formulas,
+                        preserveFormats: true,
+                        destructiveLevel: "values",
+                        reason: "Workflow repair formula errors with scoped formulas"
+                    }
+                ]
+            });
+        }
+        else if (sourceAddress !== undefined) {
+            repairResult = await runtime.fillFormulaPattern({
+                workbookId,
+                sheetName,
+                sourceAddress,
+                targetAddress,
+                direction: args.direction ?? "down"
+            });
+        }
+        else {
+            repairResult = {
+                ok: false,
+                error: {
+                    code: "FORMULA_REPAIR_SOURCE_REQUIRED",
+                    message: "Provide sourceAddress for pattern fill or formulas with formulasAddress for scoped formula repair.",
+                    retryable: false
+                }
+            };
+        }
+        const afterValidation = await runtime.validateFormulas({ workbookId, sheetName, address: targetAddress });
+        return jsonResult({
+            ok: Boolean(repairResult.ok && afterValidation.ok),
+            workflow: "excel.workflow.repair_formula_errors",
+            preflight,
+            beforeValidation,
+            patterns,
+            dependencyGraph,
+            repairResult,
+            afterValidation,
+            summary: {
+                sheetName,
+                errorAddress,
+                sourceAddress,
+                targetAddress,
+                usedDirectFormulaWrite: Array.isArray(args.formulas),
+                formulaValidationOk: afterValidation.ok,
+                formulaIssueCount: afterValidation.issueCount
+            }
+        });
+    });
+    registerMcpTool(mcp, "excel.workflow.preview_risky_edit", {
+        title: "Preview risky Excel edit",
+        description: [
+            "Run the full safe-edit workflow for scoped risky changes: before snapshot, plan preview, apply, after snapshot, diff, and rollback preview.",
+            "Use this when an edit must prove what changed and how it can be recovered instead of calling separate snapshot, batch, diff, and transaction tools.",
+            "Provide at least one scoped operation. The workflow applies by default; set apply=false only when the user asks for preview without mutation."
+        ].join(" "),
+        inputSchema: {
+            workbookId: z.string(),
+            operations: z.array(z.any()).min(1),
+            reason: z.string().optional(),
+            goal: z.string().optional(),
+            ranges: z
+                .array(z.object({
+                workbookId: z.string().optional(),
+                sheetName: z.string(),
+                address: z.string()
+            }))
+                .optional(),
+            apply: z.boolean().optional(),
+            allowSparseOverwrite: z.boolean().optional(),
+            confirmationToken: z.string().optional(),
+            agentId: z.string().optional(),
+            agentName: z.string().optional(),
+            taskId: z.string().optional(),
+            role: z.string().optional()
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            openWorldHint: false
+        }
+    }, async (args) => {
+        const workbookId = args.workbookId;
+        const preflight = await workflowPreflight(workbookId);
+        const request = {
+            workbookId,
+            operations: workflowOperations(workbookId, args.operations, args.reason ?? args.goal)
+        };
+        const ranges = workflowRanges(workbookId, args.ranges);
+        if (args.reason !== undefined) {
+            request.reason = args.reason;
+        }
+        if (args.goal !== undefined) {
+            request.goal = args.goal;
+        }
+        if (ranges !== undefined) {
+            request.ranges = ranges;
+        }
+        if (args.apply !== undefined) {
+            request.apply = args.apply;
+        }
+        if (args.allowSparseOverwrite !== undefined) {
+            request.allowSparseOverwrite = args.allowSparseOverwrite;
+        }
+        if (args.confirmationToken !== undefined) {
+            request.confirmationToken = args.confirmationToken;
+        }
+        if (args.agentId !== undefined) {
+            request.agentId = args.agentId;
+        }
+        if (args.agentName !== undefined) {
+            request.agentName = args.agentName;
+        }
+        if (args.taskId !== undefined) {
+            request.taskId = args.taskId;
+        }
+        if (args.role !== undefined) {
+            request.role = args.role;
+        }
+        const result = await runtime.previewRiskyEdit(request);
+        return jsonResult({ ...result, preflight });
+    });
+}
+async function workflowPreflight(workbookId, includePreview = true) {
+    const status = runtime.getStatus();
+    const activeContext = await runtime.getActiveContext();
+    const activeWorkbookId = activeContext.activeWorkbook?.workbookId;
+    const resolvedWorkbookId = workbookId ?? activeWorkbookId;
+    return {
+        status,
+        activeContext,
+        capabilities: runtime.getCapabilities({ includePreview }),
+        workbookMap: await runtime.getWorkbookMap(),
+        collaboration: runtime.getCollaborationStatus(resolvedWorkbookId),
+        workbookId: resolvedWorkbookId
+    };
 }
 function registerPlanTools(mcp) {
     registerMcpTool(mcp, "excel.plan.create", {
@@ -1715,7 +2361,7 @@ function styleCopyRequest(args) {
 function registerFormulaTools(mcp) {
     registerMcpTool(mcp, "excel.formula.read_patterns", {
         title: "Read formula patterns",
-        description: "Capture formulas, R1C1 pattern hashes, and pattern groups for a sheet or range.",
+        description: "Capture formulas, R1C1 pattern hashes, and pattern groups for a sheet or range. Use before formula repair; this is diagnostic and does not repair formulas by itself.",
         inputSchema: formulaPatternSchema(),
         annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
     }, async (args) => jsonResult(await runtime.readFormulaPatterns(formulaPatternRequest(args))));
@@ -1758,13 +2404,13 @@ function registerFormulaTools(mcp) {
     })));
     registerMcpTool(mcp, "excel.formula.repair_patterns", {
         title: "Repair formula patterns",
-        description: "Repair formulas from a registered template.",
+        description: "Repair formulas from a registered template. If no template fits, use formula fill tools or scoped excel.range.write_formulas, then validate.",
         inputSchema: templateRepairSchema(),
         annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false }
     }, async (args) => jsonResult(await repairTemplateFromArgs({ ...args, repair: ["formulas"] })));
     registerMcpTool(mcp, "excel.formula.find_errors", {
         title: "Find formula errors",
-        description: "Find cells with formula errors in a sheet/range.",
+        description: "Find cells with formula errors in a sheet/range before reading patterns and repairing formulas.",
         inputSchema: validationRangeSchema(),
         annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
     }, async (args) => jsonResult(await runtime.validateFormulas({
@@ -1988,7 +2634,7 @@ function registerTableTools(mcp) {
     }, async (args) => jsonResult(await runtime.resizeTable({ ...tableSelector(args), address: args.address })));
     registerMcpTool(mcp, "excel.table.reorder_columns", {
         title: "Reorder Excel table columns",
-        description: "Reorder columns in an existing structured table without clearing or recreating the table.",
+        description: "Reorder columns in an existing structured table without clearing, recreating, or range-rewriting the table.",
         inputSchema: {
             ...tableSelectorSchema(),
             columnOrder: z.array(z.union([z.string(), z.number().int().min(0)]))
@@ -2000,7 +2646,7 @@ function registerTableTools(mcp) {
     })));
     registerMcpTool(mcp, "excel.table.append_rows", {
         title: "Append Excel table rows",
-        description: "Append one or more rows to a structured table.",
+        description: "Append one or more rows to a structured table while preserving table style, filters, totals, and structured formulas.",
         inputSchema: {
             ...tableSelectorSchema(),
             values: z.array(z.array(z.any())),
@@ -2016,7 +2662,7 @@ function registerTableTools(mcp) {
     })));
     registerMcpTool(mcp, "excel.table.update_rows", {
         title: "Update Excel table rows",
-        description: "Update table rows by zero-based table-row index.",
+        description: "Update specific table rows by zero-based table-row index without rewriting the whole table.",
         inputSchema: {
             ...tableSelectorSchema(),
             rows: z.array(z.object({ index: z.number().int().min(0), values: z.array(z.any()) }))
@@ -2037,7 +2683,7 @@ function registerTableTools(mcp) {
     }, async (args) => jsonResult(await runtime.clearTableFilters(tableSelector(args))));
     registerMcpTool(mcp, "excel.table.apply_filters", {
         title: "Apply table filters",
-        description: "Apply Office.js filter criteria to table columns.",
+        description: "Apply Office.js filter criteria to table columns without reading or rewriting the full table body.",
         inputSchema: tableFilterSchema(),
         annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false }
     }, async (args) => jsonResult(await runtime.applyTableFilters({ ...tableSelector(args), filters: args.filters })));
@@ -2049,7 +2695,7 @@ function registerTableTools(mcp) {
     }, async (args) => jsonResult(await runtime.applyTableFilters({ ...tableSelector(args), filters: args.filters })));
     registerMcpTool(mcp, "excel.table.sort", {
         title: "Sort Excel table",
-        description: "Apply table sort fields.",
+        description: "Apply table sort fields while preserving the structured table, filters, formulas, and styles.",
         inputSchema: tableSortSchema(),
         annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false }
     }, async (args) => jsonResult(await runtime.sortTable({ ...tableSelector(args), fields: args.fields, matchCase: args.matchCase, method: args.method })));
@@ -2780,6 +3426,22 @@ function registerTransactionTools(mcp) {
         inputSchema: { transactionId: z.string() },
         annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
     }, async ({ transactionId }) => jsonResult(runtime.getTransaction(transactionId)));
+    registerMcpTool(mcp, "excel.transaction.wait", {
+        title: "Wait for Excel transaction",
+        description: "Wait for a queued or applying workbook transaction to reach a terminal status.",
+        inputSchema: {
+            transactionId: z.string(),
+            timeoutMs: z.number().int().positive().optional(),
+            pollMs: z.number().int().positive().optional()
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
+    }, async ({ transactionId, timeoutMs, pollMs }) => jsonResult(await runtime.waitTransaction(transactionId, timeoutMs, pollMs)));
+    registerMcpTool(mcp, "excel.transaction.cancel", {
+        title: "Cancel Excel transaction",
+        description: "Cancel a queued workbook transaction before it starts applying in Excel.",
+        inputSchema: { transactionId: z.string() },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false }
+    }, async ({ transactionId }) => jsonResult(runtime.cancelTransaction(transactionId)));
     registerMcpTool(mcp, "excel.transaction.preview_rollback", {
         title: "Preview transaction rollback",
         description: "Check whether a transaction can be rolled back without overwriting later work.",
@@ -2805,6 +3467,36 @@ function registerTransactionTools(mcp) {
         annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false }
     }, async ({ transactionId, confirmationToken }) => jsonResult(await runtime.rollbackTransactionChain(transactionId, confirmationToken)));
 }
+function registerJobTools(mcp) {
+    registerMcpTool(mcp, "excel.job.list", {
+        title: "List Excel jobs",
+        description: "List parent jobs that group multiple queued workbook transactions.",
+        inputSchema: { workbookId: z.string().optional() },
+        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
+    }, async ({ workbookId }) => jsonResult(runtime.listJobs(workbookId)));
+    registerMcpTool(mcp, "excel.job.get", {
+        title: "Get Excel job",
+        description: "Return one parent workbook job with aggregate progress across child transactions.",
+        inputSchema: { jobId: z.string() },
+        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
+    }, async ({ jobId }) => jsonResult(runtime.getJob(jobId)));
+    registerMcpTool(mcp, "excel.job.wait", {
+        title: "Wait for Excel job",
+        description: "Wait for a parent workbook job to reach a terminal status.",
+        inputSchema: {
+            jobId: z.string(),
+            timeoutMs: z.number().int().positive().optional(),
+            pollMs: z.number().int().positive().optional()
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
+    }, async ({ jobId, timeoutMs, pollMs }) => jsonResult(await runtime.waitJob(jobId, timeoutMs, pollMs)));
+    registerMcpTool(mcp, "excel.job.cancel", {
+        title: "Cancel Excel job",
+        description: "Cancel queued child transactions for a parent workbook job.",
+        inputSchema: { jobId: z.string() },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false }
+    }, async ({ jobId }) => jsonResult(runtime.cancelJob(jobId)));
+}
 function registerPermissionsTools(mcp) {
     registerMcpTool(mcp, "excel.permissions.get", {
         title: "Get permissions",
@@ -3158,7 +3850,7 @@ function registerSnapshotTools(mcp) {
     for (const name of ["excel.snapshot.create", "excel.snapshot.refresh"]) {
         registerMcpTool(mcp, name, {
             title: name.replace(/^excel\./, "").replace(/\./g, " "),
-            description: "Create or refresh a workbook snapshot.",
+            description: "Create or refresh a workbook snapshot. For risky edits, create before and after snapshots so diff tools can compare two snapshot IDs.",
             inputSchema: name.endsWith(".refresh")
                 ? { snapshotId: z.string(), reason: z.string().optional() }
                 : snapshotInputSchema(),
@@ -3192,7 +3884,7 @@ function registerSnapshotTools(mcp) {
     }, async ({ workbookId }) => jsonResult(runtime.listSnapshots(workbookId)));
     registerMcpTool(mcp, "excel.snapshot.compare", {
         title: "Compare snapshots",
-        description: "Compare two workbook snapshots.",
+        description: "Compare two workbook snapshots after capturing before and after states.",
         inputSchema: {
             leftSnapshotId: z.string(),
             rightSnapshotId: z.string()
@@ -3216,7 +3908,7 @@ function registerDiffTools(mcp) {
     for (const name of ["excel.diff.create", "excel.diff.summarize", "excel.diff.get_details", "excel.diff.export_json"]) {
         registerMcpTool(mcp, name, {
             title: name.replace(/^excel\./, "").replace(/\./g, " "),
-            description: "Create or return a diff between two stored snapshots.",
+            description: "Create or return a diff between two stored snapshots. Call after the second snapshot and before rollback preview.",
             inputSchema: {
                 leftSnapshotId: z.string(),
                 rightSnapshotId: z.string()
@@ -3697,10 +4389,19 @@ async function repairTemplateFromArgs(args) {
     }
     return runtime.repairSheetFromTemplate(request);
 }
-function registerRangeOperation(mcp, name, inputSchema, createOperation) {
+function registerRangeOperation(mcp, name, inputSchema, descriptionOrCreateOperation, maybeCreateOperation) {
+    const description = typeof descriptionOrCreateOperation === "string"
+        ? descriptionOrCreateOperation
+        : `Apply ${name} through the reversible batch pipeline.`;
+    const createOperation = typeof descriptionOrCreateOperation === "function"
+        ? descriptionOrCreateOperation
+        : maybeCreateOperation;
+    if (!createOperation) {
+        throw new Error(`Missing operation factory for ${name}`);
+    }
     registerMcpTool(mcp, name, {
         title: name.replace(/^excel\./, "").replace(/\./g, " "),
-        description: `Apply ${name} through the reversible batch pipeline.`,
+        description,
         inputSchema,
         annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false }
     }, async (args) => jsonResult(await applySingleOperation(args.workbookId, createOperation(args))));
@@ -3720,6 +4421,157 @@ async function applySingleOperation(workbookId, operation) {
         ]
     });
 }
+function workflowOperations(workbookId, operations, reason) {
+    return operations.map((operation, index) => workflowOperation(workbookId, operation, reason, index));
+}
+function workflowOperation(workbookId, operation, reason, index) {
+    if (!operation || typeof operation !== "object") {
+        throw new Error(`Workflow operation ${index + 1} must be an object.`);
+    }
+    const record = operation;
+    if (typeof record.kind === "string" && !record.kind.startsWith("excel.")) {
+        return {
+            ...record,
+            workbookId: (record.workbookId ?? workbookId),
+            operationId: (record.operationId ?? makeId("op")),
+            reason: record.reason ?? reason ?? "MCP workflow risky edit",
+            destructiveLevel: record.destructiveLevel ?? workflowDestructiveLevel(record.kind)
+        };
+    }
+    const toolName = String(record.tool ?? record.name ?? record.operation ?? record.kind ?? "");
+    const args = (record.args ?? record.input ?? record.parameters ?? record);
+    switch (toolName) {
+        case "excel.range.write_values":
+        case "range.write_values":
+            assertWorkflowRangeArgs(toolName, args);
+            return {
+                kind: "range.write_values",
+                operationId: makeId("op"),
+                workbookId,
+                target: workflowTarget(workbookId, args),
+                values: args.values,
+                preserveFormats: true,
+                destructiveLevel: "values",
+                reason: reason ?? "MCP workflow write values"
+            };
+        case "excel.range.write_formulas":
+        case "range.write_formulas":
+            assertWorkflowRangeArgs(toolName, args);
+            return {
+                kind: "range.write_formulas",
+                operationId: makeId("op"),
+                workbookId,
+                target: workflowTarget(workbookId, args),
+                formulas: args.formulas,
+                preserveFormats: true,
+                destructiveLevel: "values",
+                reason: reason ?? "MCP workflow write formulas"
+            };
+        case "excel.range.write_number_formats":
+        case "range.write_number_formats":
+            assertWorkflowRangeArgs(toolName, args);
+            return {
+                kind: "range.write_number_formats",
+                operationId: makeId("op"),
+                workbookId,
+                target: workflowTarget(workbookId, args),
+                numberFormat: args.numberFormat,
+                preserveValues: true,
+                destructiveLevel: "format",
+                reason: reason ?? "MCP workflow write number formats"
+            };
+        case "excel.range.clear_values_keep_format":
+        case "range.clear_values_keep_format":
+            assertWorkflowRangeArgs(toolName, args);
+            return {
+                kind: "range.clear_values_keep_format",
+                operationId: makeId("op"),
+                workbookId,
+                target: workflowTarget(workbookId, args),
+                destructiveLevel: "values",
+                reason: reason ?? "MCP workflow clear values"
+            };
+        case "excel.sheet.create":
+        case "sheet.create":
+            if (typeof args.sheetName !== "string") {
+                throw new Error(`${toolName} requires sheetName.`);
+            }
+            return {
+                kind: "sheet.create",
+                operationId: makeId("op"),
+                workbookId,
+                sheetName: args.sheetName,
+                activate: args.activate,
+                destructiveLevel: "structure",
+                reason: reason ?? "MCP workflow sheet create"
+            };
+        default:
+            throw new Error(`Unsupported workflow operation: ${toolName || "unknown"}. Use scoped range writes, clear-values-keep-format, sheet.create, or canonical ExcelOperation objects.`);
+    }
+}
+function workflowRanges(workbookId, ranges) {
+    if (!Array.isArray(ranges)) {
+        return undefined;
+    }
+    return ranges.map((range, index) => {
+        if (!range || typeof range !== "object") {
+            throw new Error(`Workflow range ${index + 1} must be an object.`);
+        }
+        const record = range;
+        if (typeof record.sheetName !== "string" || typeof record.address !== "string") {
+            throw new Error(`Workflow range ${index + 1} requires sheetName and address.`);
+        }
+        return {
+            workbookId: (record.workbookId ?? workbookId),
+            sheetName: record.sheetName,
+            address: record.address
+        };
+    });
+}
+function workflowTarget(workbookId, args) {
+    return {
+        workbookId: (args.workbookId ?? workbookId),
+        sheetName: args.sheetName,
+        address: args.address
+    };
+}
+function assertWorkflowRangeArgs(toolName, args) {
+    if (typeof args.sheetName !== "string" || typeof args.address !== "string") {
+        throw new Error(`${toolName} requires sheetName and address so the workflow can snapshot a scoped range.`);
+    }
+}
+function workflowDestructiveLevel(kind) {
+    if (kind.startsWith("sheet.") || kind.startsWith("template.")) {
+        return "structure";
+    }
+    if (kind.includes("style") || kind.includes("format")) {
+        return "format";
+    }
+    if (kind.startsWith("range.")) {
+        return "values";
+    }
+    return "workbook";
+}
+function styleEntriesToOperations(workbookId, entries, reason) {
+    return entries.map((entry) => ({
+        kind: "range.write_styles",
+        operationId: makeId("op"),
+        workbookId,
+        target: {
+            workbookId,
+            sheetName: entry.sheetName,
+            address: entry.address
+        },
+        style: entry.style,
+        preserveValues: true,
+        destructiveLevel: "format",
+        reason: entry.reason ?? reason ?? "MCP bulk range write styles"
+    }));
+}
+function styleBatchChunkSize() {
+    const value = Number(process.env.OPEN_WORKBOOK_STYLE_BATCH_CHUNK_SIZE ?? 25);
+    return Number.isFinite(value) && value > 0 ? Math.round(value) : 25;
+}
 function targetFromArgs(args) {
     return {
         workbookId: args.workbookId,