@components-kit/open-workbook 0.1.4 → 0.1.6

package/assets/backend/dist/runtime-service.js

@@ -1,13 +1,13 @@
 import { mkdir, readFile, stat, unlink, writeFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import path from "node:path";
-import { BackupManager, BatchCompiler, DefaultPermissionPolicy, buildFormulaDependencyGraph, attachConflictGuidance, extractFormulaReferences, hashStable, LockManager, formatA1Address, parseA1Address, PlanManager, SnapshotManager, TaskRegistry, TemplateRegistry, TransactionManager, traceDependents, tracePrecedents } from "@components-kit/open-workbook-excel-core";
+import { BackupManager, BatchCompiler, cellCount, DefaultPermissionPolicy, buildFormulaDependencyGraph, attachConflictGuidance, extractFormulaReferences, hashStable, LockManager, formatA1Address, parseA1Address, PlanManager, SnapshotManager, TaskRegistry, TemplateRegistry, TransactionManager, traceDependents, tracePrecedents } from "@components-kit/open-workbook-excel-core";
 import { makeRollbackConflict } from "@components-kit/open-workbook-excel-core";
 import { getToolCatalogSummary, PromptCatalog, ResourceCatalog, makeId, runtimeError } from "@components-kit/open-workbook-protocol";
 import { SessionRegistry } from "./session-registry.js";
 import { NativeFileBridge } from "./native-file-bridge.js";
 import { RuntimeStateStore } from "./state-store.js";
-const runtimeVersion = process.env.OPEN_WORKBOOK_VERSION ?? "0.1.4";
+const runtimeVersion = process.env.OPEN_WORKBOOK_VERSION ?? "0.1.6";
 export class RuntimeService {
     sessions = new SessionRegistry();
     backups = new BackupManager();
@@ -21,10 +21,14 @@ export class RuntimeService {
     addinClients = new Map();
     regions = new Map();
     agents = new Map();
+    jobs = new Map();
     collabEvents = [];
     conflicts = [];
     conflictTelemetry = [];
     transactionQueue = Promise.resolve();
+    runtimeMutationActive = false;
+    runtimeMutationQueuedCount = 0;
+    cancelledQueuedTransactions = new Set();
     defaultAgentId = "agent_daemon";
     stateStore;
     fileBridge;
@@ -357,14 +361,70 @@ export class RuntimeService {
         return { ok: result.missingLockIds.length === 0, released: result.released, missingLockIds: result.missingLockIds };
     }
     listTransactions(workbookId) {
-        return { ok: true, transactions: this.transactions.list(workbookId) };
+        return {
+            ok: true,
+            transactions: this.transactions.list(workbookId).map((transaction) => this.transactions.withQueueMetadata(transaction))
+        };
     }
     getTransaction(transactionId) {
         const transaction = this.transactions.get(transactionId);
         return transaction
-            ? { ok: true, transaction }
+            ? { ok: true, transaction: this.transactions.withQueueMetadata(transaction) }
             : { ok: false, error: runtimeError("NOT_FOUND", `Transaction not found: ${transactionId}`, { retryable: false }) };
     }
+    async waitTransaction(transactionId, timeoutMs = 30_000, pollMs = 250) {
+        const started = Date.now();
+        while (true) {
+            const transaction = this.transactions.get(transactionId);
+            if (!transaction) {
+                return { ok: false, completed: false, error: runtimeError("NOT_FOUND", `Transaction not found: ${transactionId}`, { retryable: false }) };
+            }
+            const withMetadata = this.transactions.withQueueMetadata(transaction);
+            if (isTerminalTransactionStatus(withMetadata.status)) {
+                return { ok: true, completed: true, transaction: withMetadata };
+            }
+            if (Date.now() - started >= timeoutMs) {
+                return {
+                    ok: true,
+                    completed: false,
+                    transaction: withMetadata,
+                    error: runtimeError("TIMEOUT", `Timed out waiting for transaction ${transactionId}.`, { retryable: true })
+                };
+            }
+            await sleep(Math.max(25, pollMs));
+        }
+    }
+    cancelTransaction(transactionId) {
+        const transaction = this.transactions.get(transactionId);
+        if (!transaction) {
+            return { ok: false, error: runtimeError("NOT_FOUND", `Transaction not found: ${transactionId}`, { retryable: false }) };
+        }
+        if (transaction.status !== "queued") {
+            return {
+                ok: false,
+                transaction: this.transactions.withQueueMetadata(transaction),
+                error: runtimeError("OPERATION_FAILED", `Only queued transactions can be cancelled. Current status: ${transaction.status}.`, { retryable: false })
+            };
+        }
+        this.cancelledQueuedTransactions.add(transactionId);
+        const cancelled = this.transactions.markCancelled(transactionId);
+        this.recordCollabEvent({
+            type: "transaction.cancelled",
+            workbookId: cancelled.workbookId,
+            agentId: cancelled.agentId,
+            taskId: cancelled.taskId,
+            transactionId,
+            message: cancelled.progressMessage ?? "Queued transaction cancelled.",
+            details: { transaction: cancelled }
+        });
+        if (cancelled.taskId !== undefined) {
+            this.updateTask(cancelled.taskId, { status: "cancelled", errorMessage: cancelled.errorMessage });
+        }
+        else {
+            this.persistState();
+        }
+        return { ok: true, transaction: this.transactions.withQueueMetadata(cancelled) };
+    }
     previewTransactionRollback(transactionId) {
         const transaction = this.transactions.get(transactionId);
         if (!transaction) {
@@ -752,6 +812,10 @@ export class RuntimeService {
             this.lockLeasePolicy = normalizeLockLeasePolicy(snapshot.lockLeasePolicy);
         }
         this.transactions.load(snapshot.transactions);
+        this.jobs.clear();
+        for (const job of snapshot.jobs ?? []) {
+            this.jobs.set(job.jobId, { ...job, transactionIds: [...job.transactionIds], warnings: [...job.warnings] });
+        }
         this.conflicts.splice(0, this.conflicts.length, ...snapshot.conflicts.slice(-250));
         this.conflictTelemetry.splice(0, this.conflictTelemetry.length, ...(snapshot.conflictTelemetry ?? []).slice(-1_000));
         this.collabEvents.splice(0, this.collabEvents.length, ...snapshot.collaborationEvents.slice(-1_000));
@@ -817,6 +881,7 @@ export class RuntimeService {
             locks: this.locks.dump(),
             lockLeasePolicy: this.lockLeasePolicy,
             transactions: this.transactions.dump(),
+            jobs: [...this.jobs.values()].map((job) => ({ ...job, transactionIds: [...job.transactionIds], warnings: [...job.warnings] })),
             conflicts: this.conflicts.slice(-250),
             conflictTelemetry: this.conflictTelemetry.slice(-1_000),
             collaborationEvents: this.collabEvents.slice(-1_000),
@@ -1104,6 +1169,247 @@ export class RuntimeService {
     compileBatch(request) {
         return this.compiler.compile(request);
     }
+    preflightBatch(request) {
+        const compiled = this.compiler.compile(request);
+        const estimatedPayloadBytes = Buffer.byteLength(JSON.stringify(request.operations), "utf8");
+        const chunkPlan = planBatchChunks(request.operations);
+        const warnings = [];
+        const needsQueue = request.operations.length > batchDirectOperationThreshold() ||
+            estimatedPayloadBytes > batchDirectPayloadThresholdBytes() ||
+            compiled.estimatedCellsTouched > batchDirectCellThreshold() ||
+            (chunkPlan.safeToAutoChunk && chunkPlan.chunksTotal > 1);
+        let recommendedExecutionMode = needsQueue ? "submit" : "apply";
+        if (needsQueue && chunkPlan.safeToAutoChunk && chunkPlan.chunksTotal > 1) {
+            recommendedExecutionMode = "chunked_submit";
+            warnings.push({
+                code: "LARGE_BATCH_WILL_BE_CHUNKED",
+                message: `Batch is large and can be safely split into ${chunkPlan.chunksTotal} queued chunks.`,
+                details: { strategy: chunkPlan.strategy, chunkSize: chunkPlan.chunkSize }
+            });
+        }
+        else if (needsQueue) {
+            warnings.push({
+                code: "LARGE_BATCH_SHOULD_BE_QUEUED",
+                message: "Batch is large enough that it should be submitted to the serialized queue instead of applied synchronously.",
+                details: {
+                    operationThreshold: batchDirectOperationThreshold(),
+                    payloadThresholdBytes: batchDirectPayloadThresholdBytes(),
+                    cellThreshold: batchDirectCellThreshold()
+                }
+            });
+        }
+        return {
+            ok: true,
+            workbookId: request.workbookId,
+            operationCount: request.operations.length,
+            estimatedCellsTouched: compiled.estimatedCellsTouched,
+            estimatedPayloadBytes,
+            destructiveLevel: compiled.destructiveLevel,
+            recommendedExecutionMode,
+            safeToAutoChunk: chunkPlan.safeToAutoChunk,
+            chunkPlan: chunkPlan.strategy === "none" ? undefined : chunkPlan,
+            warnings
+        };
+    }
+    submitChunkedBatch(request, input = {}) {
+        if (request.mode !== "apply") {
+            return {
+                ok: false,
+                error: runtimeError("INVALID_ARGUMENT", "Only apply-mode batches can be submitted as chunked jobs.", { retryable: false })
+            };
+        }
+        const preflight = this.preflightBatch(request);
+        if (!preflight.safeToAutoChunk || preflight.chunkPlan === undefined || preflight.chunkPlan.chunksTotal <= 1) {
+            const submitted = this.submitBatch(request);
+            return {
+                ok: submitted.ok,
+                status: "queued",
+                progressMessage: "Batch was not safely chunkable, so it was submitted as one queued transaction.",
+                preflight,
+                transactionIds: submitted.transactionId ? [submitted.transactionId] : [],
+                transactions: [submitted]
+            };
+        }
+        const chunks = chunkBatchOperations(request.operations);
+        const now = new Date().toISOString();
+        const compiled = this.compiler.compile(request);
+        const agentId = request.agentId ?? this.defaultAgentId;
+        const job = {
+            jobId: makeId("job"),
+            workbookId: request.workbookId,
+            agentId,
+            kind: preflight.chunkPlan.strategy === "split_style_entries" ? "style_chunked" : preflight.chunkPlan.strategy === "split_matrix_rows" ? "matrix_chunked" : "batch_chunked",
+            status: "queued",
+            goal: input.goal ?? request.progressMessage ?? "Apply chunked Excel batch",
+            transactionIds: [],
+            chunksTotal: chunks.length,
+            chunksCompleted: 0,
+            progressMessage: `Queued ${chunks.length} workbook update chunks.`,
+            retryStrategy: input.retryStrategy ?? preflight.chunkPlan.strategy,
+            destructiveLevel: compiled.destructiveLevel,
+            warnings: preflight.warnings,
+            queuedAt: now
+        };
+        if (request.taskId !== undefined) {
+            job.taskId = request.taskId;
+        }
+        if (request.planId !== undefined) {
+            job.planId = request.planId;
+        }
+        this.jobs.set(job.jobId, job);
+        const transactions = chunks.map((chunk, index) => this.submitBatch({
+            ...request,
+            operations: chunk,
+            retryStrategy: job.retryStrategy,
+            chunksTotal: chunks.length,
+            chunksCompleted: index,
+            progressMessage: `Queued workbook update chunk ${index + 1} of ${chunks.length}.`
+        }));
+        job.transactionIds = transactions.map((transaction) => transaction.transactionId).filter(Boolean);
+        this.refreshJob(job.jobId);
+        this.persistState();
+        return {
+            ok: true,
+            status: "queued",
+            job: this.getJobRecord(job.jobId),
+            jobId: job.jobId,
+            preflight,
+            retryStrategy: job.retryStrategy,
+            chunksTotal: chunks.length,
+            chunksCompleted: 0,
+            transactionIds: job.transactionIds,
+            transactions,
+            progressMessage: `Batch is large, so Open Workbook queued it as job ${job.jobId} with ${chunks.length} chunks. Use excel.job.wait or excel.job.get for progress.`
+        };
+    }
+    listJobs(workbookId) {
+        return {
+            ok: true,
+            jobs: [...this.jobs.values()]
+                .filter((job) => workbookId === undefined || job.workbookId === workbookId)
+                .map((job) => this.refreshJob(job.jobId))
+                .sort((a, b) => (b.finishedAt ?? b.startedAt ?? b.queuedAt).localeCompare(a.finishedAt ?? a.startedAt ?? a.queuedAt))
+        };
+    }
+    getJob(jobId) {
+        const job = this.getJobRecord(jobId);
+        return job
+            ? { ok: true, job }
+            : { ok: false, error: runtimeError("NOT_FOUND", `Job not found: ${jobId}`, { retryable: false }) };
+    }
+    async waitJob(jobId, timeoutMs = 30_000, pollMs = 250) {
+        const started = Date.now();
+        while (true) {
+            const job = this.getJobRecord(jobId);
+            if (!job) {
+                return { ok: false, completed: false, error: runtimeError("NOT_FOUND", `Job not found: ${jobId}`, { retryable: false }) };
+            }
+            if (isTerminalJobStatus(job.status)) {
+                return { ok: true, completed: true, job };
+            }
+            if (Date.now() - started >= timeoutMs) {
+                return {
+                    ok: true,
+                    completed: false,
+                    job,
+                    error: runtimeError("TIMEOUT", `Timed out waiting for job ${jobId}.`, { retryable: true })
+                };
+            }
+            await sleep(Math.max(25, pollMs));
+        }
+    }
+    cancelJob(jobId) {
+        const job = this.getJobRecord(jobId);
+        if (!job) {
+            return { ok: false, error: runtimeError("NOT_FOUND", `Job not found: ${jobId}`, { retryable: false }) };
+        }
+        const cancelled = [];
+        const skipped = [];
+        for (const transactionId of job.transactionIds) {
+            const transaction = this.transactions.get(transactionId);
+            if (!transaction) {
+                continue;
+            }
+            if (transaction.status === "queued") {
+                const result = this.cancelTransaction(transactionId);
+                if (result.ok && result.transaction) {
+                    cancelled.push(result.transaction);
+                }
+            }
+            else if (!isTerminalTransactionStatus(transaction.status)) {
+                skipped.push(this.transactions.withQueueMetadata(transaction));
+            }
+        }
+        const refreshed = this.refreshJob(jobId);
+        this.persistState();
+        return {
+            ok: skipped.length === 0,
+            job: refreshed,
+            cancelledTransactions: cancelled,
+            skippedTransactions: skipped,
+            progressMessage: skipped.length === 0
+                ? `Cancelled queued work for job ${jobId}.`
+                : `Cancelled queued chunks for job ${jobId}; ${skipped.length} chunk(s) were already applying and could not be cancelled.`
+        };
+    }
+    getJobRecord(jobId) {
+        const job = this.jobs.get(jobId);
+        return job ? { ...this.refreshJob(jobId), transactionIds: [...job.transactionIds], warnings: [...job.warnings] } : undefined;
+    }
+    refreshJob(jobId) {
+        const job = this.jobs.get(jobId);
+        if (!job) {
+            throw new Error(`Job not found: ${jobId}`);
+        }
+        const transactions = job.transactionIds.map((transactionId) => this.transactions.get(transactionId)).filter((transaction) => transaction !== undefined);
+        const appliedCount = transactions.filter((transaction) => transaction.status === "applied").length;
+        const terminalTransactions = transactions.filter((transaction) => isTerminalTransactionStatus(transaction.status));
+        const failed = transactions.find((transaction) => transaction.status === "failed" || transaction.status === "blocked");
+        const applying = transactions.some((transaction) => transaction.status === "applying");
+        const queued = transactions.some((transaction) => transaction.status === "queued");
+        const cancelledCount = transactions.filter((transaction) => transaction.status === "cancelled").length;
+        let status = job.status;
+        if (transactions.length === 0) {
+            status = "queued";
+        }
+        else if (appliedCount === transactions.length) {
+            status = "applied";
+        }
+        else if (cancelledCount === transactions.length) {
+            status = "cancelled";
+        }
+        else if (terminalTransactions.length === transactions.length && appliedCount > 0) {
+            status = "partially_applied";
+        }
+        else if (terminalTransactions.length === transactions.length) {
+            status = failed !== undefined ? "failed" : "cancelled";
+        }
+        else if (failed !== undefined) {
+            status = appliedCount > 0 ? "partially_applied" : "failed";
+        }
+        else if (appliedCount > 0 && terminalTransactions.length < transactions.length) {
+            status = "partially_applied";
+        }
+        else if (applying) {
+            status = "applying";
+        }
+        else if (queued) {
+            status = "queued";
+        }
+        const now = new Date().toISOString();
+        job.status = status;
+        job.chunksCompleted = appliedCount;
+        job.startedAt = job.startedAt ?? transactions.find((transaction) => transaction.startedAt !== undefined)?.startedAt;
+        if (isTerminalJobStatus(status)) {
+            job.finishedAt = job.finishedAt ?? now;
+        }
+        if (failed !== undefined) {
+            job.errorCode = failed.errorCode;
+            job.errorMessage = failed.errorMessage;
+        }
+        job.progressMessage = jobProgressMessage(job, transactions.length);
+        return job;
+    }
     async previewPlan(planId) {
         const preview = this.plans.previewPlan(planId);
         const client = this.getActiveAddinClient();
@@ -3929,6 +4235,151 @@ export class RuntimeService {
         this.plans.markApplyResult(planId, result);
         return { ...result, planId };
     }
+    async previewRiskyEdit(input) {
+        const goal = input.goal ?? input.reason ?? "Scoped risky edit";
+        if (input.operations.length === 0) {
+            return {
+                ok: false,
+                workflow: "excel.workflow.preview_risky_edit",
+                applied: false,
+                completedSteps: [],
+                errorStep: "operations",
+                error: runtimeError("INVALID_ARGUMENT", "previewRiskyEdit requires at least one scoped operation.", {
+                    retryable: false
+                })
+            };
+        }
+        const sparseWarnings = detectSparseOverwriteWarnings(input.operations);
+        if (sparseWarnings.length > 0 && input.allowSparseOverwrite !== true) {
+            return {
+                ok: false,
+                workflow: "excel.workflow.preview_risky_edit",
+                applied: false,
+                completedSteps: [],
+                errorStep: "sparse_write_guard",
+                warnings: sparseWarnings,
+                error: runtimeError("INVALID_ARGUMENT", "Risky workflow blocked a sparse/null-padded range write. Use the smallest changed range, use clear_values_keep_format for explicit clearing, or pass allowSparseOverwrite when this broad overwrite is intentional.", {
+                    retryable: false,
+                    details: { warnings: sparseWarnings }
+                })
+            };
+        }
+        const ranges = input.ranges?.length ? input.ranges : snapshotRangesFromOperations(input.workbookId, input.operations);
+        const before = await this.createWorkbookSnapshot({
+            workbookId: input.workbookId,
+            reason: `Before ${goal}`,
+            ...(ranges.length > 0 ? { ranges } : {})
+        });
+        if (!before.ok || !("snapshot" in before)) {
+            return {
+                ok: false,
+                workflow: "excel.workflow.preview_risky_edit",
+                applied: false,
+                completedSteps: [],
+                errorStep: "before_snapshot",
+                beforeSnapshotResult: before
+            };
+        }
+        const planRequest = {
+            workbookId: input.workbookId,
+            goal,
+            operations: input.operations,
+            baseSnapshotId: before.snapshot.snapshotId
+        };
+        if (input.agentId !== undefined) {
+            planRequest.agentId = input.agentId;
+        }
+        if (input.agentName !== undefined) {
+            planRequest.agentName = input.agentName;
+        }
+        if (input.taskId !== undefined) {
+            planRequest.taskId = input.taskId;
+        }
+        if (input.role !== undefined) {
+            planRequest.role = input.role;
+        }
+        const plan = this.createPlan(planRequest);
+        const planPreview = await this.previewPlan(plan.planId);
+        const completedSteps = ["before_snapshot", "plan_create", "plan_preview"];
+        if (input.apply === false) {
+            return {
+                ok: true,
+                workflow: "excel.workflow.preview_risky_edit",
+                applied: false,
+                completedSteps,
+                planId: plan.planId,
+                beforeSnapshot: before.snapshot,
+                planPreview,
+                recovery: {
+                    beforeSnapshotId: before.snapshot.snapshotId,
+                    rollbackAvailable: false
+                },
+                nextSteps: ["Apply the previewed plan with excel.plan.apply, then capture an after snapshot, diff, and rollback preview."]
+            };
+        }
+        const applyResult = await this.applyPlan(plan.planId, input.confirmationToken);
+        completedSteps.push("plan_apply");
+        if (!applyResult.ok) {
+            return {
+                ok: false,
+                workflow: "excel.workflow.preview_risky_edit",
+                applied: false,
+                completedSteps,
+                errorStep: "plan_apply",
+                planId: plan.planId,
+                transactionId: applyResult.transactionId,
+                beforeSnapshot: before.snapshot,
+                planPreview,
+                applyResult,
+                recovery: {
+                    beforeSnapshotId: before.snapshot.snapshotId,
+                    transactionId: applyResult.transactionId,
+                    rollbackAvailable: false
+                }
+            };
+        }
+        const after = await this.createWorkbookSnapshot({
+            workbookId: input.workbookId,
+            reason: `After ${goal}`,
+            ranges: before.snapshot.affectedRanges
+        });
+        if (after.ok && "snapshot" in after) {
+            completedSteps.push("after_snapshot");
+        }
+        const diff = after.ok && "snapshot" in after
+            ? this.compareSnapshots(before.snapshot.snapshotId, after.snapshot.snapshotId)
+            : undefined;
+        if (diff?.ok) {
+            completedSteps.push("snapshot_diff");
+        }
+        const rollbackPreview = applyResult.transactionId !== undefined
+            ? this.previewTransactionRollback(applyResult.transactionId)
+            : undefined;
+        if (rollbackPreview !== undefined) {
+            completedSteps.push("rollback_preview");
+        }
+        return {
+            ok: Boolean(after.ok && diff?.ok),
+            workflow: "excel.workflow.preview_risky_edit",
+            applied: true,
+            completedSteps,
+            summary: riskyEditSummary(applyResult, diff, rollbackPreview),
+            planId: plan.planId,
+            transactionId: applyResult.transactionId,
+            beforeSnapshot: before.snapshot,
+            afterSnapshot: after.ok && "snapshot" in after ? after.snapshot : undefined,
+            planPreview,
+            applyResult,
+            diff,
+            rollbackPreview,
+            recovery: {
+                beforeSnapshotId: before.snapshot.snapshotId,
+                afterSnapshotId: after.ok && "snapshot" in after ? after.snapshot.snapshotId : undefined,
+                transactionId: applyResult.transactionId,
+                rollbackAvailable: rollbackPreview?.rollbackAvailable ?? false
+            }
+        };
+    }
     async rollbackPlan(planId, confirmationToken) {
         const plan = this.plans.getPlan(planId);
         if (!plan?.preview) {
@@ -3997,6 +4448,34 @@ export class RuntimeService {
         if (request.mode !== "apply") {
             return this.applyBatchDirect(request);
         }
+        const returnQueuedProgress = this.isRuntimeMutationBusy();
+        const scheduled = this.scheduleBatch(request);
+        if (returnQueuedProgress) {
+            void scheduled.promise.catch(() => undefined);
+            return queuedOperationResult(this.transactions.withQueueMetadata(scheduled.transaction));
+        }
+        return scheduled.promise;
+    }
+    submitBatch(request) {
+        if (request.mode !== "apply") {
+            return {
+                ok: false,
+                error: runtimeError("INVALID_ARGUMENT", "Only apply-mode batches can be submitted to the mutation queue.", { retryable: false })
+            };
+        }
+        const scheduled = this.scheduleBatch(request);
+        void scheduled.promise.catch(() => undefined);
+        const transaction = this.transactions.withQueueMetadata(scheduled.transaction);
+        return {
+            ok: true,
+            transactionId: transaction.transactionId,
+            status: transaction.status,
+            queuePosition: transaction.queuePosition,
+            progressMessage: transaction.progressMessage,
+            transaction
+        };
+    }
+    scheduleBatch(request) {
         const compiled = this.compiler.compile(request);
         const agentId = request.agentId ?? this.defaultAgentId;
         const scopes = scopesFromBatch(request.workbookId, request.operations);
@@ -4008,7 +4487,11 @@ export class RuntimeService {
             goal: request.operations.map((operation) => operation.reason || operation.kind).join("; ") || "Apply Excel batch",
             scopes,
             baseFingerprints: request.expectedTargetFingerprints ?? [],
-            destructiveLevel: compiled.destructiveLevel
+            destructiveLevel: compiled.destructiveLevel,
+            progressMessage: request.progressMessage,
+            retryStrategy: request.retryStrategy,
+            chunksTotal: request.chunksTotal,
+            chunksCompleted: request.chunksCompleted
         });
         if (request.taskId !== undefined) {
             this.tasks.attachTransaction(request.taskId, transaction.transactionId);
@@ -4022,7 +4505,7 @@ export class RuntimeService {
             transactionId: transaction.transactionId,
             message: `Transaction queued: ${transaction.goal}`
         });
-        return this.enqueueTransaction(async () => {
+        const promise = this.enqueueTransaction(transaction.transactionId, async () => {
             const lockResult = this.locks.acquire({
                 workbookId: request.workbookId,
                 ownerAgentId: agentId,
@@ -4055,6 +4538,8 @@ export class RuntimeService {
                 return {
                     ok: false,
                     transactionId: transaction.transactionId,
+                    transactionStatus: "blocked",
+                    progressMessage: "Workbook mutation is blocked by an active lock.",
                     taskId: request.taskId,
                     agentId,
                     rollbackAvailable: compiled.requiredBackups.length > 0,
@@ -4099,6 +4584,8 @@ export class RuntimeService {
                 const enriched = {
                     ...result,
                     transactionId: transaction.transactionId,
+                    transactionStatus: result.ok ? "applied" : "failed",
+                    progressMessage: result.ok ? "Workbook mutation applied successfully." : (result.error?.message ?? "Workbook mutation failed."),
                     agentId
                 };
                 if (request.taskId !== undefined) {
@@ -4140,6 +4627,82 @@ export class RuntimeService {
                 }
                 return enriched;
             }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const code = /timed out|timeout/i.test(message) ? "TIMEOUT" : "TRANSACTION_FAILED";
+                if (code === "TIMEOUT" && shouldRetryStyleBatch(request)) {
+                    const chunks = chunkOperationsForRetry(request.operations);
+                    const warnings = [
+                        {
+                            code: "RETRYING_SMALLER_BATCH",
+                            message: `Style batch timed out and was resubmitted as ${chunks.length} smaller queued chunks.`
+                        }
+                    ];
+                    this.transactions.markFailed(transaction.transactionId, code, message, warnings);
+                    if (request.taskId !== undefined) {
+                        this.updateTask(request.taskId, { status: "queued", currentStep: "Retrying style update in smaller chunks" });
+                    }
+                    this.recordCollabEvent({
+                        type: "transaction.failed",
+                        workbookId: request.workbookId,
+                        agentId,
+                        taskId: request.taskId,
+                        transactionId: transaction.transactionId,
+                        message: `${message}; retrying style update in smaller chunks.`
+                    });
+                    const retryTransactions = chunks.map((chunk, index) => this.submitBatch({
+                        ...request,
+                        operations: chunk,
+                        retryStrategy: "retry_timeout_split_style_entries",
+                        chunksTotal: chunks.length,
+                        chunksCompleted: index,
+                        progressMessage: `Retrying style update chunk ${index + 1} of ${chunks.length}.`
+                    }));
+                    return {
+                        ok: true,
+                        transactionId: transaction.transactionId,
+                        transactionStatus: "failed",
+                        progressMessage: `Style batch timed out, so Open Workbook queued ${chunks.length} smaller retry chunks.`,
+                        taskId: request.taskId,
+                        agentId,
+                        rollbackAvailable: false,
+                        backups: [],
+                        warnings,
+                        telemetry: { warningCount: warnings.length },
+                        data: {
+                            retryStrategy: "retry_timeout_split_style_entries",
+                            chunksTotal: chunks.length,
+                            retryTransactionIds: retryTransactions.map((retry) => retry.transactionId).filter(Boolean),
+                            retryTransactions
+                        }
+                    };
+                }
+                this.transactions.markFailed(transaction.transactionId, code, message);
+                if (request.taskId !== undefined) {
+                    this.updateTask(request.taskId, { status: "failed", errorMessage: message });
+                }
+                this.recordCollabEvent({
+                    type: "transaction.failed",
+                    workbookId: request.workbookId,
+                    agentId,
+                    taskId: request.taskId,
+                    transactionId: transaction.transactionId,
+                    message
+                });
+                return {
+                    ok: false,
+                    transactionId: transaction.transactionId,
+                    transactionStatus: "failed",
+                    progressMessage: message,
+                    taskId: request.taskId,
+                    agentId,
+                    rollbackAvailable: compiled.requiredBackups.length > 0,
+                    backups: [],
+                    warnings: [],
+                    telemetry: { warningCount: 0 },
+                    error: runtimeError(code === "TIMEOUT" ? "TIMEOUT" : "OPERATION_FAILED", message, { retryable: code === "TIMEOUT" })
+                };
+            }
             finally {
                 const releasedLocks = this.locks.release(lockResult.locks.map((lock) => lock.lockId));
                 this.markConflictTelemetryClearedByLock(releasedLocks.map((lock) => lock.lockId));
@@ -4160,15 +4723,36 @@ export class RuntimeService {
                 }
             }
         });
+        return { transaction, promise };
     }
-    enqueueTransaction(work) {
-        return this.enqueueRuntimeMutation(work);
+    enqueueTransaction(transactionId, work) {
+        return this.enqueueRuntimeMutation(async () => {
+            const transaction = this.transactions.get(transactionId);
+            if (this.cancelledQueuedTransactions.delete(transactionId) || transaction?.status === "cancelled") {
+                return cancelledOperationResult(transactionId);
+            }
+            return work();
+        });
     }
     enqueueRuntimeMutation(work) {
-        const run = this.transactionQueue.then(work, work);
+        this.runtimeMutationQueuedCount += 1;
+        const run = this.transactionQueue.then(() => this.runQueuedRuntimeMutation(work), () => this.runQueuedRuntimeMutation(work));
         this.transactionQueue = run.then(() => undefined, () => undefined);
         return run;
     }
+    async runQueuedRuntimeMutation(work) {
+        this.runtimeMutationQueuedCount = Math.max(0, this.runtimeMutationQueuedCount - 1);
+        this.runtimeMutationActive = true;
+        try {
+            return await work();
+        }
+        finally {
+            this.runtimeMutationActive = false;
+        }
+    }
+    isRuntimeMutationBusy() {
+        return this.runtimeMutationActive || this.runtimeMutationQueuedCount > 0;
+    }
     async applyDirectTransaction(input, work) {
         const agentId = input.agentId ?? this.defaultAgentId;
         const transaction = this.transactions.create({
@@ -5243,6 +5827,85 @@ function scopesFromBatch(workbookId, operations) {
     }
     return dedupeScopes(scopes.length > 0 ? scopes : [{ type: "workbook", workbookId }]);
 }
+function snapshotRangesFromOperations(workbookId, operations) {
+    const ranges = [];
+    for (const scope of scopesFromBatch(workbookId, operations)) {
+        if (scope.type === "range" && scope.address !== undefined) {
+            ranges.push({
+                workbookId: scope.workbookId,
+                sheetName: scope.sheetName,
+                address: scope.address
+            });
+        }
+    }
+    const seen = new Set();
+    return ranges.filter((range) => {
+        const key = `${range.workbookId}:${range.sheetName}:${range.address}`;
+        if (seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        return true;
+    });
+}
+function detectSparseOverwriteWarnings(operations) {
+    const warnings = [];
+    for (const operation of operations) {
+        if (operation.kind !== "range.write_values") {
+            continue;
+        }
+        const values = operation.values;
+        if (!Array.isArray(values) || values.length === 0) {
+            continue;
+        }
+        const matrixCells = values.reduce((sum, row) => sum + (Array.isArray(row) ? row.length : 0), 0);
+        const nonEmptyCells = values.reduce((sum, row) => sum + (Array.isArray(row) ? row.filter((value) => value !== null && value !== undefined && value !== "").length : 0), 0);
+        const targetCells = cellCount(operation.target.address);
+        const touchedCells = Math.max(matrixCells, targetCells);
+        if (touchedCells < 8 || nonEmptyCells === 0) {
+            continue;
+        }
+        const nonEmptyRatio = nonEmptyCells / touchedCells;
+        if (nonEmptyRatio <= 0.25 && touchedCells - nonEmptyCells >= 4) {
+            warnings.push({
+                code: "SPARSE_RANGE_WRITE_RISK",
+                message: `Sparse range write to ${operation.target.sheetName}!${operation.target.address} has ${nonEmptyCells}/${touchedCells} non-empty cell(s). Use a smaller range or an explicit clear operation.`,
+                target: operation.target,
+                details: {
+                    operationId: operation.operationId,
+                    nonEmptyCells,
+                    touchedCells,
+                    nonEmptyRatio
+                }
+            });
+        }
+    }
+    return warnings;
+}
+function riskyEditSummary(applyResult, diffResult, rollbackPreview) {
+    const diff = diffResult?.diff;
+    return {
+        transactionId: applyResult.transactionId,
+        backupIds: applyResult.backups,
+        warningCount: applyResult.warnings.length,
+        diff: diff
+            ? {
+                changedRanges: diff.changedRanges,
+                cellsChanged: diff.cellsChanged,
+                formulasChanged: diff.formulasChanged,
+                stylesChanged: diff.stylesChanged,
+                tablesChanged: diff.tablesChanged,
+                sheetsChanged: diff.sheetsChanged,
+                destructiveLevel: diff.destructiveLevel
+            }
+            : undefined,
+        rollback: {
+            previewed: rollbackPreview !== undefined,
+            available: rollbackPreview?.rollbackAvailable ?? false,
+            conflictCount: Array.isArray(rollbackPreview?.conflicts) ? rollbackPreview.conflicts.length : 0
+        }
+    };
+}
 function tableMutationScopes(request, ranges) {
     const scopes = ranges.map(rangeScope);
     if (request.tableName !== undefined) {
@@ -6062,6 +6725,201 @@ function telemetryBuckets(records, keySelector) {
     }))
         .sort((a, b) => b.count - a.count || b.lastSeenAt.localeCompare(a.lastSeenAt));
 }
+function isTerminalTransactionStatus(status) {
+    return ["applied", "failed", "blocked", "rolled_back", "cancelled"].includes(status);
+}
+function isTerminalJobStatus(status) {
+    return ["applied", "failed", "partially_applied", "cancelled"].includes(status);
+}
+function jobProgressMessage(job, knownTransactionCount) {
+    switch (job.status) {
+        case "queued":
+            return `Workbook job is queued with ${knownTransactionCount || job.chunksTotal} chunk(s).`;
+        case "applying":
+            return `Workbook job is applying ${job.chunksCompleted} of ${job.chunksTotal} chunk(s).`;
+        case "partially_applied":
+            return job.errorMessage
+                ? `Workbook job partially applied ${job.chunksCompleted} of ${job.chunksTotal} chunk(s): ${job.errorMessage}`
+                : `Workbook job partially applied ${job.chunksCompleted} of ${job.chunksTotal} chunk(s).`;
+        case "applied":
+            return `Workbook job applied all ${job.chunksTotal} chunk(s).`;
+        case "failed":
+            return job.errorMessage ? `Workbook job failed: ${job.errorMessage}` : "Workbook job failed.";
+        case "cancelled":
+            return "Workbook job was cancelled before all chunks applied.";
+    }
+}
+function planBatchChunks(operations) {
+    const chunkedOperations = chunkBatchOperations(operations);
+    if (chunkedOperations.length <= 1 || chunkedOperations.length === operations.length) {
+        return {
+            strategy: "none",
+            chunksTotal: 1,
+            chunkSize: operations.length,
+            operationCount: operations.length,
+            chunkedOperationKinds: [],
+            safeToAutoChunk: false
+        };
+    }
+    const allChunkable = operations.every((operation) => isStyleChunkableOperation(operation) || isMatrixChunkableOperation(operation));
+    if (!allChunkable) {
+        return {
+            strategy: "none",
+            chunksTotal: 1,
+            chunkSize: operations.length,
+            operationCount: operations.length,
+            chunkedOperationKinds: [],
+            safeToAutoChunk: false
+        };
+    }
+    const hasStyle = operations.some(isStyleChunkableOperation);
+    const hasMatrix = operations.some(isMatrixChunkableOperation);
+    const chunkSize = hasMatrix ? matrixChunkRowCount() : styleBatchChunkSize();
+    return {
+        strategy: hasStyle && hasMatrix ? "mixed" : hasMatrix ? "split_matrix_rows" : "split_style_entries",
+        chunksTotal: chunkedOperations.length,
+        chunkSize,
+        operationCount: operations.length,
+        chunkedOperationKinds: [...new Set(operations.map((operation) => operation.kind))],
+        safeToAutoChunk: true
+    };
+}
+function chunkBatchOperations(operations) {
+    if (operations.length === 0) {
+        return [];
+    }
+    if (operations.every(isStyleChunkableOperation)) {
+        return chunkArray(operations, styleBatchChunkSize());
+    }
+    if (!operations.every((operation) => isStyleChunkableOperation(operation) || isMatrixChunkableOperation(operation))) {
+        return [operations];
+    }
+    const chunks = [];
+    for (const operation of operations) {
+        if (isMatrixChunkableOperation(operation)) {
+            chunks.push(...chunkMatrixOperation(operation));
+        }
+        else {
+            chunks.push([operation]);
+        }
+    }
+    return chunks.length > 1 ? chunks : [operations];
+}
+function isStyleChunkableOperation(operation) {
+    return operation.kind === "range.write_styles";
+}
+function isMatrixChunkableOperation(operation) {
+    return operation.kind === "range.write_values" || operation.kind === "range.write_formulas" || operation.kind === "range.write_number_formats";
+}
+function chunkMatrixOperation(operation) {
+    const matrix = matrixForOperation(operation);
+    const rowCount = matrix.length;
+    const chunkRows = matrixChunkRowCount();
+    if (rowCount <= chunkRows) {
+        return [[operation]];
+    }
+    const chunks = [];
+    const parsed = parseA1Address(stripSheetName(operation.target.address));
+    for (let start = 0; start < rowCount; start += chunkRows) {
+        const rows = matrix.slice(start, start + chunkRows);
+        const address = formatA1Address({
+            ...parsed,
+            startRow: parsed.startRow + start,
+            endRow: parsed.startRow + start + rows.length - 1
+        });
+        chunks.push([cloneMatrixOperation(operation, rows, address)]);
+    }
+    return chunks;
+}
+function matrixForOperation(operation) {
+    switch (operation.kind) {
+        case "range.write_values":
+            return operation.values;
+        case "range.write_formulas":
+            return operation.formulas;
+        case "range.write_number_formats":
+            return operation.numberFormat;
+    }
+}
+function cloneMatrixOperation(operation, rows, address) {
+    const target = { ...operation.target, address };
+    switch (operation.kind) {
+        case "range.write_values":
+            return { ...operation, operationId: makeId("op"), target, values: rows };
+        case "range.write_formulas":
+            return { ...operation, operationId: makeId("op"), target, formulas: rows };
+        case "range.write_number_formats":
+            return { ...operation, operationId: makeId("op"), target, numberFormat: rows };
+    }
+}
+function batchDirectOperationThreshold() {
+    return positiveIntegerEnv("OPEN_WORKBOOK_BATCH_DIRECT_OPERATION_THRESHOLD", 25);
+}
+function batchDirectPayloadThresholdBytes() {
+    return positiveIntegerEnv("OPEN_WORKBOOK_BATCH_DIRECT_PAYLOAD_BYTES", 512_000);
+}
+function batchDirectCellThreshold() {
+    return positiveIntegerEnv("OPEN_WORKBOOK_BATCH_DIRECT_CELL_THRESHOLD", 50_000);
+}
+function styleBatchChunkSize() {
+    return positiveIntegerEnv("OPEN_WORKBOOK_STYLE_BATCH_CHUNK_SIZE", 25);
+}
+function matrixChunkRowCount() {
+    return positiveIntegerEnv("OPEN_WORKBOOK_MATRIX_CHUNK_ROWS", 500);
+}
+function positiveIntegerEnv(name, fallback) {
+    const value = Number(process.env[name] ?? fallback);
+    return Number.isFinite(value) && value > 0 ? Math.round(value) : fallback;
+}
+function chunkArray(items, size) {
+    const chunks = [];
+    for (let index = 0; index < items.length; index += size) {
+        chunks.push(items.slice(index, index + size));
+    }
+    return chunks;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function cancelledOperationResult(transactionId) {
+    return {
+        ok: false,
+        transactionId,
+        transactionStatus: "cancelled",
+        progressMessage: "Queued workbook mutation was cancelled before it reached Excel.",
+        rollbackAvailable: false,
+        backups: [],
+        warnings: [],
+        telemetry: { warningCount: 0 },
+        error: runtimeError("TRANSACTION_CANCELLED", "Queued workbook mutation was cancelled before it reached Excel.", { retryable: false })
+    };
+}
+function queuedOperationResult(transaction) {
+    return {
+        ok: true,
+        transactionId: transaction.transactionId,
+        transactionStatus: "queued",
+        queuePosition: transaction.queuePosition,
+        progressMessage: transaction.progressMessage ?? "Workbook mutation is queued and will apply when earlier workbook work finishes.",
+        rollbackAvailable: false,
+        backups: [],
+        warnings: [],
+        telemetry: { warningCount: 0 }
+    };
+}
+function shouldRetryStyleBatch(request) {
+    return request.retryStrategy !== "retry_timeout_split_style_entries"
+        && request.operations.length > 1
+        && request.operations.every((operation) => operation.kind === "range.write_styles");
+}
+function chunkOperationsForRetry(operations) {
+    const chunkSize = Math.max(1, Math.ceil(operations.length / 2));
+    const chunks = [];
+    for (let index = 0; index < operations.length; index += chunkSize) {
+        chunks.push(operations.slice(index, index + chunkSize));
+    }
+    return chunks;
+}
 function scopeTelemetryKey(scope) {
     switch (scope.type) {
         case "workbook":