@components-kit/open-workbook 0.1.5 → 0.1.7

package/assets/excel-addin/manifest.xml

@@ -5,7 +5,7 @@
   xmlns:ov="http://schemas.microsoft.com/office/taskpaneappversionoverrides"
   xsi:type="TaskPaneApp">
   <Id>6f2d2ac1-69b0-4eb6-a256-0a1fcb000001</Id>
-  <Version>0.1.5.0</Version>
+  <Version>0.1.7.0</Version>
   <ProviderName>ComponentsKit</ProviderName>
   <DefaultLocale>en-US</DefaultLocale>
   <DisplayName DefaultValue="OpenWorkbook" />

package/assets/instructions/open-workbook-excel/SKILL.md

@@ -25,6 +25,7 @@ If the add-in is disconnected, ask the user to start their agent UI so it launch
 - Use `excel.table.*` for structured table rows, filters, sorts, totals, and table resizing.
 - Use `excel.template.*`, `excel.style.*`, and `excel.formula.*` when preserving or repairing templates matters.
 - Use `excel.plan.*` for previewable multi-step changes that need rollback and stale-target checks.
+- Use `excel.batch.preflight` before large generated writes, then choose direct apply, queued submit, or `excel.batch.submit_chunked` with job progress based on the recommendation.
 - Use `excel.batch.*` for compact, direct range mutations that still need backups, fingerprints, permissions, and transaction logging.
 - Use `excel.workflow.create_formula_sheet` for standard sheet creation with values, formulas, number formats, and formula validation in one response.
 - Use `excel.workflow.repair_formula_errors` for formula error repair when you have an error range plus a source formula range or exact formulas to write.
@@ -33,7 +34,7 @@ If the add-in is disconnected, ask the user to start their agent UI so it launch
 - Use `excel.workflow.create_pivot_chart_summary` for standard PivotTable plus chart summary tasks that need create, refresh, and validation in one response.
 Combined mutating workflows include a read-only preflight payload before mutation; still prefer `excel.workflow.prepare_session` first when possible.
 - Use `excel.validate.*` before and after risky changes.
-- Use `excel.backup.*`, `excel.snapshot.*`, and `excel.transaction.*` for recovery, audit, rollback previews, and rollback chains.
+- Use `excel.backup.*`, `excel.snapshot.*`, `excel.transaction.*`, and `excel.job.*` for recovery, audit, long-running progress, rollback previews, and rollback chains.
 - Use `excel.task.*`, `excel.lock.*`, `excel.collab.*`, and `excel.conflict.*` for multi-agent workbook work.
 
 For detailed routing, read `references/tool-selection.md`.
@@ -51,12 +52,12 @@ For detailed routing, read `references/tool-selection.md`.
 ## Critical Recipes
 
 - Sheet with formulas: prefer `excel.workflow.create_formula_sheet`; if using separate tools, create the sheet, write labels/constants with `excel.range.write_values`, write formulas with `excel.range.write_formulas`, write number formats with `excel.range.write_number_formats`, then validate with `excel.formula.validate` or `excel.validate.no_formula_errors`. Do not put formula strings into `write_values`.
-- Large table reorder/filter/sort/append/update: inspect with `excel.table.get_info` and bounded `excel.table.read` only when row data is needed, then use `excel.table.reorder_columns`, `excel.table.apply_filters`, `excel.table.sort`, `excel.table.append_rows`, or `excel.table.update_rows`. Never clear, recreate, or rewrite the whole table for these tasks.
+- Large table reorder/filter/sort/append/update: always inspect the table first with `excel.table.get_info` or `excel.workbook.get_workbook_map`. Use bounded `excel.table.read` only when row data is needed, then use `excel.table.reorder_columns`, `excel.table.apply_filters`, `excel.table.sort`, `excel.table.append_rows`, or `excel.table.update_rows`. For table filters, prefer `excel.table.apply_filters` over generic filter tools. After mutation, validate with `excel.validate.tables` for table changes and `excel.validate.filters` for filter/sort changes. Never clear, recreate, or rewrite the whole table for these tasks.
 - Formula repair: prefer `excel.workflow.repair_formula_errors` when the error range and source formula range are known. Otherwise find errors, read nearby formula patterns, inspect dependencies, repair with `excel.formula.repair_patterns`, `excel.formula.fill_down`, `excel.formula.fill_right`, or scoped `excel.range.write_formulas`, recalculate if needed, then validate. Never convert formulas to values unless explicitly requested.
 - Template report: prefer `excel.workflow.create_template_report`; if using separate tools, create the sheet from template, clear/fill declared regions, compare styles, repair style drift, and validate against the template.
 - Snapshot/diff/rollback preview: after discovery, prefer `excel.workflow.preview_risky_edit` for a scoped risky edit with a non-empty minimal operation list. If using separate tools, create a before snapshot, make the scoped change, create an after snapshot, call `excel.diff.summarize` or `excel.snapshot.compare` with both snapshot IDs, then use rollback preview tools without actually rolling back unless asked.
 - Pivot/chart summary: prefer `excel.workflow.create_pivot_chart_summary`; if using separate tools, check capability, create the PivotTable, refresh it, create/update the chart, refresh/update the chart source, and validate the PivotTable source before reporting success.
-- Multi-agent work: read collaboration status, create or inspect the task, acquire the narrowest lock, follow conflict guidance, perform or plan the scoped operation, then release locks.
+- Multi-agent work: start with `excel.collab.get_status`, create or inspect the task, acquire the narrowest lock, follow conflict guidance, perform or plan the scoped operation, then release locks.
 
 ## Workflow References
 

package/assets/instructions/open-workbook-excel/references/performance.md

@@ -24,12 +24,16 @@ Avoid workbook-wide reads unless the task is search, validation, audit, or disco
 ## Writes
 
 - Use one batch or plan for related edits.
+- Preflight large generated batches before applying them.
 - Keep matrix shapes exact: rows and columns must match the target range.
-- Let Open Workbook chunk large values/formulas/number formats through its batch compiler.
+- Let Open Workbook chunk large values/formulas/number formats through safe row-based chunk plans.
 - Avoid alternating read/write/read/write loops. Read once, compute, apply once, validate once.
+- If work is queued or applying, report the progress message to the user and wait/poll the job or transaction rather than starting parallel mutations.
 
 For very large writes, consider a plan preview first so the agent can expose scope, chunk count, and rollback coverage before applying.
 
+Automatic timeout retry is limited to style-only batches because repeating the same style is safe. Values, formulas, and number formats should be chunked before execution when preflight recommends it. For tables, pivots, charts, and structure, inspect transaction status before retrying.
+
 ## Formulas
 
 - Prefer formula pattern tools for repeated formula layouts.

package/assets/instructions/open-workbook-excel/references/tool-selection.md

@@ -32,17 +32,24 @@ Use explicit sheet/address ranges whenever possible. Use used-range or workbook-
 - Simple formulas: `excel.range.write_formulas`
 - Number formats: `excel.range.write_number_formats`
 - Styles: `excel.range.write_styles`
+- Grouped styles: `excel.range.write_styles_many`
 - Combined formula sheet creation: `excel.workflow.create_formula_sheet`
 - Combined formula error repair: `excel.workflow.repair_formula_errors`
-- Multiple related range edits: `excel.batch.validate`, `excel.batch.dry_run`, `excel.batch.apply`
+- Multiple related range edits: `excel.batch.validate`, `excel.batch.preflight`, `excel.batch.dry_run`, `excel.batch.apply`
+- Long-running related range edits: `excel.batch.submit`
+- Preflighted chunked range edits: `excel.batch.submit_chunked`
+- Chunked long-running jobs: `excel.job.get`, `excel.job.wait`, `excel.job.cancel`
 - Scoped risky edit with diff and rollback preview: `excel.workflow.preview_risky_edit`
 - Previewable or user-reviewable edits: `excel.plan.create`, `excel.plan.preview`, `excel.plan.apply`
 - Stale plan handling: `excel.plan.refresh_preview`, `excel.plan.rebase`
+- Queued mutation status: `excel.transaction.get`, `excel.transaction.wait`, `excel.transaction.cancel`
 
-Prefer `excel.workflow.create_formula_sheet` for standard new sheets that need values, formulas, number formats, and validation. Prefer `excel.workflow.repair_formula_errors` for formula error repair when an error range and source formula range are known. Prefer `excel.workflow.preview_risky_edit` when a risky scoped edit should apply and return before/after snapshots, a diff, transaction id, and rollback preview in one response. Provide at least one minimal scoped operation and leave `apply` enabled unless the user asked for preview only. Prefer `excel.plan.*` when a user should review a diff before applying, when formulas/templates are at risk, or when rollback clarity matters. Prefer `excel.batch.*` for compact, well-scoped range mutations.
+Prefer `excel.workflow.create_formula_sheet` for standard new sheets that need values, formulas, number formats, and validation. Prefer `excel.workflow.repair_formula_errors` for formula error repair when an error range and source formula range are known. Prefer `excel.workflow.preview_risky_edit` when a risky scoped edit should apply and return before/after snapshots, a diff, transaction id, and rollback preview in one response. Provide at least one minimal scoped operation and leave `apply` enabled unless the user asked for preview only. Prefer `excel.plan.*` when a user should review a diff before applying, when formulas/templates are at risk, or when rollback clarity matters. Prefer `excel.batch.*` for compact, well-scoped range mutations. Preflight large generated batches before applying them.
 Combined mutating workflows include an internal read-only preflight payload before mutation; still prefer `excel.workflow.prepare_session` first when possible.
 Values, formulas, formats, and styles are separate workbook facets. Use `excel.range.write_values` for constants only, `excel.range.write_formulas` for formulas beginning with `=`, and `excel.range.write_number_formats` for display formats. Do not merge formulas into a values write just because the matrix is convenient.
 Do not pad a large range write with `null`, blank strings, or unchanged cells when only one cell or a smaller rectangle should change. Use the smallest changed target range, or use `excel.range.clear_values_keep_format` for intentional clearing.
+Use `excel.range.write_styles_many` for report styling that touches many ranges, such as title bands, headers, zebra rows, status colors, or type colors. Use single `excel.range.write_styles` only for one contiguous range. Large grouped style updates may return queued parent jobs; wait or poll their job IDs.
+If a mutation returns queued or applying transaction or job state, tell the user the workbook update is still running, then call `excel.job.wait`, `excel.job.get`, `excel.transaction.wait`, or `excel.transaction.get` instead of launching parallel writes. Use cancel tools only for queued work that should not start.
 
 When a noninteractive agent run cannot apply a mutation, create an `excel.plan.create` draft with operations that use actual MCP tool names and nested `args`. Example operations should look like `{ "tool": "excel.range.write_formulas", "args": { ... } }`, not vague prose or broad workbook rewrites.
 
@@ -56,6 +63,7 @@ When a noninteractive agent run cannot apply a mutation, create an `excel.plan.c
 - Sorts: `excel.sort.apply`, `excel.sort.clear`
 
 Use table tools instead of range tools when the target is an Excel table. This preserves headers, totals rows, filters, structured references, and table styles.
+Before table reorder, filter, sort, append, or update operations, call `excel.table.get_info` or `excel.workbook.get_workbook_map`. For table filters, use `excel.table.apply_filters` rather than generic filter tools. After table structure or row mutations, call `excel.validate.tables`; after filter/sort changes, call `excel.validate.filters`.
 Do not clear and recreate a table to reorder columns; use `excel.table.reorder_columns`, or stop for confirmation before any destructive rebuild.
 For large tables, avoid full `excel.table.read` unless the user asks for all rows. Pass `rowLimit`, `rowOffset`, and `columns` for targeted discovery, then mutate with table-native tools.
 

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.5";
+const runtimeVersion = process.env.OPEN_WORKBOOK_VERSION ?? "0.1.7";
 const server = new McpServer({
     name: "open-workbook",
     version: runtimeVersion
@@ -73,6 +73,7 @@ registerCollaborationTools(server);
 registerLockTools(server);
 registerConflictTools(server);
 registerTransactionTools(server);
+registerJobTools(server);
 registerPermissionsTools(server);
 registerCleanTools(server);
 registerValidateTools(server);
@@ -1118,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(),
@@ -1205,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.",
@@ -1269,6 +1319,98 @@ 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", {
@@ -3284,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.",
@@ -3309,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",
@@ -4364,6 +4552,26 @@ function workflowDestructiveLevel(kind) {
     }
     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,