hoi4-agent-tools 0.1.6 → 0.2.0

package/dist/hoi4_agent_tools/mcp/server/base-tools.js

@@ -4,6 +4,7 @@ import { boundedSourceHashEvidence, publicArtifactLink } from '../../core/artifa
 import { workspaceRegistrationSchema } from '../../core/configuration.js';
 import { emptyServiceResult, ServiceError } from '../../core/result.js';
 import { parseClausewitz } from '../../core/source/index.js';
+import { TRANSACTION_MAX_DIAGNOSTICS } from '../../core/transaction-limits.js';
 import { importContinuousFocusPalettes, importFocusTrees, layoutFocusTreeAsync, lintContinuousFocusPalette, lintFocusTree, } from '../../focus/index.js';
 import { ScriptedGuiStudio } from '../../gui/index.js';
 import { AgentNudger, attributeMapValidationDiagnostics } from '../../map/index.js';
@@ -260,7 +261,7 @@ function focusReferences(engineSnapshot) {
         helper: active('scripted_effect'),
     };
 }
-async function postValidateTransaction(engine, transaction, principal, signal) {
+export async function postValidateTransaction(engine, transaction, principal, signal, autonomous = false) {
     engine.invalidate(transaction.workspaceId);
     const snapshot = await engine.scan(transaction.workspaceId, {}, principal, signal);
     const changed = new Set(transaction.files.map(({ relativePath }) => sourcePathComparisonKey(relativePath)));
@@ -273,7 +274,9 @@ async function postValidateTransaction(engine, transaction, principal, signal) {
     const checks = [];
     if (transaction.operationKind === 'focus-plan-changes') {
         const catalog = focusReferences(snapshot);
-        for (const file of snapshot.files.filter(({ shadowedBy, relativePath }) => shadowedBy === undefined && changed.has(sourcePathComparisonKey(relativePath)))) {
+        for (const file of snapshot.files.filter(({ shadowedBy, relativePath }) => shadowedBy === undefined &&
+            relativePath.toLowerCase().endsWith('.txt') &&
+            changed.has(sourcePathComparisonKey(relativePath)))) {
             const document = parseClausewitz(file.bytes, file.displayPath);
             const imported = importFocusTrees(document, { references: catalog });
             diagnostics.push(...imported.diagnostics);
@@ -296,7 +299,9 @@ async function postValidateTransaction(engine, transaction, principal, signal) {
         });
     }
     else if (transaction.operationKind === 'continuous-focus-plan-changes') {
-        for (const file of snapshot.files.filter(({ shadowedBy, relativePath }) => shadowedBy === undefined && changed.has(sourcePathComparisonKey(relativePath)))) {
+        for (const file of snapshot.files.filter(({ shadowedBy, relativePath }) => shadowedBy === undefined &&
+            relativePath.toLowerCase().endsWith('.txt') &&
+            changed.has(sourcePathComparisonKey(relativePath)))) {
             const document = parseClausewitz(file.bytes, file.displayPath);
             const imported = importContinuousFocusPalettes(document);
             diagnostics.push(...imported.diagnostics);
@@ -353,7 +358,71 @@ async function postValidateTransaction(engine, transaction, principal, signal) {
             ? 'Changed source reparsed and reindexed successfully'
             : 'Changed source has blocking post-write diagnostics',
     });
-    return { diagnostics, checks };
+    const availableDiagnostics = Math.max(0, TRANSACTION_MAX_DIAGNOSTICS - transaction.diagnostics.length);
+    if (diagnostics.length > availableDiagnostics) {
+        const workspace = engine.resolver.get(transaction.workspaceId, principal);
+        const sourceEvidence = boundedSourceHashEvidence(Object.fromEntries(transaction.files.flatMap(({ relativePath, afterSha256 }) => afterSha256 === null ? [] : [[relativePath, afterSha256]])));
+        const artifact = await engine.artifacts.putChunked(workspace, autonomous
+            ? `${transaction.operationKind}.post-validation.json`
+            : `${transaction.transactionId}.post-validation.json`, 'application/json', `${canonicalJson({
+            schemaVersion: 1,
+            ...(autonomous
+                ? { execution: 'autonomous-rewrite' }
+                : {
+                    transactionId: transaction.transactionId,
+                    planHash: transaction.planHash,
+                }),
+            operationKind: transaction.operationKind,
+            diagnosticCount: diagnostics.length,
+            checks,
+            diagnostics,
+        })}\n`, {
+            kind: autonomous ? 'autonomous-rewrite-post-validation' : 'transaction-post-validation',
+            toolVersion: PACKAGE_VERSION,
+            schemaVersion: autonomous
+                ? 'autonomous-rewrite-post-validation.v1'
+                : 'transaction-post-validation.v1',
+            sourceHashes: sourceEvidence.sourceHashes,
+            metadata: { sourceHashInventory: sourceEvidence.inventory },
+        }, 'Complete source-linked diagnostics from post-write transaction validation', signal);
+        const retainedLimit = Math.max(0, availableDiagnostics - 1);
+        const hard = diagnostics.filter(({ severity }) => severity === 'error' || severity === 'blocker');
+        const retainedHard = hard.slice(0, retainedLimit);
+        const retainedSoft = diagnostics
+            .filter(({ severity }) => severity !== 'error' && severity !== 'blocker')
+            .slice(0, retainedLimit - retainedHard.length);
+        const omittedHard = hard.length - retainedHard.length;
+        const artifactLink = publicArtifactLink(artifact);
+        checks.push({
+            id: 'post-write-diagnostics-resource',
+            passed: omittedHard === 0,
+            message: `Complete post-write diagnostics are stored at ${artifactLink.uri}`,
+        });
+        return {
+            diagnostics: availableDiagnostics === 0
+                ? []
+                : [
+                    ...retainedHard,
+                    ...retainedSoft,
+                    {
+                        code: 'POST_VALIDATION_DIAGNOSTICS_IN_RESOURCE',
+                        severity: omittedHard > 0 ? 'blocker' : 'warning',
+                        category: 'transaction',
+                        message: `Complete post-write validation contains ${diagnostics.length} diagnostics and is stored as an MCP resource`,
+                        details: {
+                            total: diagnostics.length,
+                            returned: availableDiagnostics,
+                            omitted: diagnostics.length - retainedLimit,
+                            omittedHard,
+                            artifact: artifactLink,
+                        },
+                    },
+                ],
+            checks,
+            artifacts: [artifactLink],
+        };
+    }
+    return { diagnostics, checks, artifacts: [] };
 }
 export function registerBaseTools(server, engine, context) {
     server.registerTool('hoi4.project_register', {
@@ -499,7 +568,7 @@ export function registerBaseTools(server, engine, context) {
                         passed: true,
                         message: snapshot.complete
                             ? `${snapshot.index.symbols.length} symbols indexed from a complete inventory`
-                            : `${snapshot.index.symbols.length} symbols indexed; ${snapshot.skippedSourceCount} over-limit source(s) were skipped`,
+                            : `${snapshot.index.symbols.length} symbols indexed from an incomplete inventory; ${snapshot.skippedSourceCount} over-limit source(s) were recorded and aggregate index ceilings may also apply`,
                     },
                 ],
             };
@@ -510,229 +579,239 @@ export function registerBaseTools(server, engine, context) {
             return errorResult(error, workspaceId);
         }
     });
-    server.registerTool('hoi4.transaction_status', {
-        title: 'Inspect transaction',
-        description: 'Return compact dry-run/apply/rollback counts and current state with a complete manifest resource.',
-        inputSchema: workspaceInput.extend({ transactionId: transactionIdSchema }).strict(),
-        outputSchema: transactionStatusOutputSchema,
-        annotations: readOnly,
-    }, async ({ workspaceId, transactionId }, extra) => {
-        try {
-            const progress = progressReporter(extra);
-            progress.signal.throwIfAborted();
-            const manifest = await engine.transactions.status(workspaceId, transactionId, context.principal, progress.signal);
-            progress.signal.throwIfAborted();
-            const result = emptyServiceResult(workspaceId, { manifest: transactionSummary(manifest) });
-            result.code = 'TRANSACTION_STATUS';
-            result.transactionId = manifest.transactionId;
-            result.planHash = manifest.planHash;
-            result.proposedFiles = manifest.files.slice(0, 100).map(({ relativePath }) => relativePath);
-            result.changedFiles = manifest.appliedFiles.slice(0, 100);
-            result.artifacts = [transactionResourceLink(manifest)];
-            result.validation = manifest.validation;
-            result.rollbackStatus = manifest.rollbackStatus;
-            return toolResult(result);
-        }
-        catch (error) {
-            return errorResult(error, workspaceId);
-        }
-    });
-    server.registerTool('hoi4.transaction_diff', {
-        title: 'Review transaction diff',
-        description: 'Page through the complete affected-file set, operation summaries, and source/binary artifact links before apply.',
-        inputSchema: workspaceInput
-            .extend({
-            transactionId: transactionIdSchema,
-            limit: z.number().int().min(1).max(20).default(20),
-            cursor: z.string().min(1).max(4096).optional(),
-        })
-            .strict(),
-        outputSchema: transactionDiffOutputSchema,
-        annotations: readOnly,
-    }, async ({ workspaceId, transactionId, limit, cursor }, extra) => {
-        try {
-            const progress = progressReporter(extra);
-            progress.signal.throwIfAborted();
-            const manifest = await engine.transactions.status(workspaceId, transactionId, context.principal, progress.signal);
-            progress.signal.throwIfAborted();
-            let fileOffset = 0;
-            let operationOffset = 0;
-            let artifactOffset = 0;
-            if (cursor !== undefined) {
-                const decoded = decodeTransactionDiffCursor(cursor);
-                if (decoded.planHash !== manifest.planHash ||
-                    decoded.fileOffset > manifest.files.length ||
-                    decoded.operationOffset > manifest.operations.length ||
-                    decoded.artifactOffset > manifest.artifacts.length) {
-                    throw new ServiceError('TRANSACTION_CURSOR_STALE', 'Transaction plan changed or the diff cursor is stale');
+    if (engine.resolver.config().writePolicy !== 'autonomous') {
+        server.registerTool('hoi4.transaction_status', {
+            title: 'Inspect transaction',
+            description: 'Return compact dry-run/apply/rollback counts and current state with a complete manifest resource.',
+            inputSchema: workspaceInput.extend({ transactionId: transactionIdSchema }).strict(),
+            outputSchema: transactionStatusOutputSchema,
+            annotations: readOnly,
+        }, async ({ workspaceId, transactionId }, extra) => {
+            try {
+                const progress = progressReporter(extra);
+                progress.signal.throwIfAborted();
+                const manifest = await engine.transactions.status(workspaceId, transactionId, context.principal, progress.signal);
+                progress.signal.throwIfAborted();
+                const result = emptyServiceResult(workspaceId, {
+                    manifest: transactionSummary(manifest),
+                });
+                result.code = 'TRANSACTION_STATUS';
+                result.transactionId = manifest.transactionId;
+                result.planHash = manifest.planHash;
+                result.proposedFiles = manifest.files
+                    .slice(0, 100)
+                    .map(({ relativePath }) => relativePath);
+                result.changedFiles = manifest.appliedFiles.slice(0, 100);
+                result.artifacts = [transactionResourceLink(manifest)];
+                result.validation = manifest.validation;
+                result.rollbackStatus = manifest.rollbackStatus;
+                return toolResult(result);
+            }
+            catch (error) {
+                return errorResult(error, workspaceId);
+            }
+        });
+        server.registerTool('hoi4.transaction_diff', {
+            title: 'Review transaction diff',
+            description: 'Page through the complete affected-file set, operation summaries, and source/binary artifact links before apply.',
+            inputSchema: workspaceInput
+                .extend({
+                transactionId: transactionIdSchema,
+                limit: z.number().int().min(1).max(20).default(20),
+                cursor: z.string().min(1).max(4096).optional(),
+            })
+                .strict(),
+            outputSchema: transactionDiffOutputSchema,
+            annotations: readOnly,
+        }, async ({ workspaceId, transactionId, limit, cursor }, extra) => {
+            try {
+                const progress = progressReporter(extra);
+                progress.signal.throwIfAborted();
+                const manifest = await engine.transactions.status(workspaceId, transactionId, context.principal, progress.signal);
+                progress.signal.throwIfAborted();
+                let fileOffset = 0;
+                let operationOffset = 0;
+                let artifactOffset = 0;
+                if (cursor !== undefined) {
+                    const decoded = decodeTransactionDiffCursor(cursor);
+                    if (decoded.planHash !== manifest.planHash ||
+                        decoded.fileOffset > manifest.files.length ||
+                        decoded.operationOffset > manifest.operations.length ||
+                        decoded.artifactOffset > manifest.artifacts.length) {
+                        throw new ServiceError('TRANSACTION_CURSOR_STALE', 'Transaction plan changed or the diff cursor is stale');
+                    }
+                    fileOffset = decoded.fileOffset;
+                    operationOffset = decoded.operationOffset;
+                    artifactOffset = decoded.artifactOffset;
                 }
-                fileOffset = decoded.fileOffset;
-                operationOffset = decoded.operationOffset;
-                artifactOffset = decoded.artifactOffset;
+                const manifestFiles = manifest.files.slice(fileOffset, fileOffset + limit);
+                const files = manifestFiles.map(({ relativePath, operationIds, beforeSha256, afterSha256, beforeSize, afterSize, mediaType, diffArtifact, }) => ({
+                    relativePath,
+                    operationIdCount: operationIds.length,
+                    operationIds: operationIds.slice(0, 20),
+                    beforeSha256,
+                    afterSha256,
+                    beforeSize,
+                    afterSize,
+                    mediaType,
+                    ...(diffArtifact === undefined ? {} : { diffArtifact }),
+                }));
+                const operations = manifest.operations.slice(operationOffset, operationOffset + limit);
+                const artifacts = manifest.artifacts.slice(artifactOffset, artifactOffset + limit);
+                const nextFileOffset = fileOffset + manifestFiles.length;
+                const nextOperationOffset = operationOffset + operations.length;
+                const nextArtifactOffset = artifactOffset + artifacts.length;
+                const nextCursor = nextFileOffset < manifest.files.length ||
+                    nextOperationOffset < manifest.operations.length ||
+                    nextArtifactOffset < manifest.artifacts.length
+                    ? encodeTransactionDiffCursor(manifest.planHash, nextFileOffset, nextOperationOffset, nextArtifactOffset)
+                    : undefined;
+                const result = emptyServiceResult(workspaceId, {
+                    files,
+                    operations: operations.map(({ id, kind, summary }) => ({ id, kind, summary })),
+                    fileCount: manifest.files.length,
+                    operationCount: manifest.operations.length,
+                    artifactCount: manifest.artifacts.length,
+                    returnedFiles: files.length,
+                    returnedOperations: operations.length,
+                    returnedArtifacts: artifacts.length,
+                    ...(nextCursor === undefined ? {} : { nextCursor }),
+                    expiresAt: manifest.expiresAt,
+                });
+                result.code = 'TRANSACTION_DIFF';
+                result.transactionId = manifest.transactionId;
+                result.planHash = manifest.planHash;
+                result.proposedFiles = files.map(({ relativePath }) => relativePath);
+                result.artifacts = [transactionResourceLink(manifest), ...artifacts];
+                result.validation = manifest.validation;
+                result.rollbackStatus = manifest.rollbackStatus;
+                return toolResult(result);
             }
-            const manifestFiles = manifest.files.slice(fileOffset, fileOffset + limit);
-            const files = manifestFiles.map(({ relativePath, operationIds, beforeSha256, afterSha256, beforeSize, afterSize, mediaType, diffArtifact, }) => ({
-                relativePath,
-                operationIdCount: operationIds.length,
-                operationIds: operationIds.slice(0, 20),
-                beforeSha256,
-                afterSha256,
-                beforeSize,
-                afterSize,
-                mediaType,
-                ...(diffArtifact === undefined ? {} : { diffArtifact }),
-            }));
-            const operations = manifest.operations.slice(operationOffset, operationOffset + limit);
-            const artifacts = manifest.artifacts.slice(artifactOffset, artifactOffset + limit);
-            const nextFileOffset = fileOffset + manifestFiles.length;
-            const nextOperationOffset = operationOffset + operations.length;
-            const nextArtifactOffset = artifactOffset + artifacts.length;
-            const nextCursor = nextFileOffset < manifest.files.length ||
-                nextOperationOffset < manifest.operations.length ||
-                nextArtifactOffset < manifest.artifacts.length
-                ? encodeTransactionDiffCursor(manifest.planHash, nextFileOffset, nextOperationOffset, nextArtifactOffset)
-                : undefined;
-            const result = emptyServiceResult(workspaceId, {
-                files,
-                operations: operations.map(({ id, kind, summary }) => ({ id, kind, summary })),
-                fileCount: manifest.files.length,
-                operationCount: manifest.operations.length,
-                artifactCount: manifest.artifacts.length,
-                returnedFiles: files.length,
-                returnedOperations: operations.length,
-                returnedArtifacts: artifacts.length,
-                ...(nextCursor === undefined ? {} : { nextCursor }),
-                expiresAt: manifest.expiresAt,
-            });
-            result.code = 'TRANSACTION_DIFF';
-            result.transactionId = manifest.transactionId;
-            result.planHash = manifest.planHash;
-            result.proposedFiles = files.map(({ relativePath }) => relativePath);
-            result.artifacts = [transactionResourceLink(manifest), ...artifacts];
-            result.validation = manifest.validation;
-            result.rollbackStatus = manifest.rollbackStatus;
-            return toolResult(result);
-        }
-        catch (error) {
-            return errorResult(error, workspaceId);
-        }
-    });
-    server.registerTool('hoi4.transaction_apply', {
-        title: 'Apply reviewed transaction',
-        description: 'Apply a completed dry run only when transaction ID, workspace, principal, source hashes, and expected plan hash still match.',
-        inputSchema: transactionInput,
-        outputSchema: transactionMutationOutputSchema,
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: true,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    }, async ({ workspaceId, transactionId, expectedPlanHash }, extra) => {
-        try {
-            requireServerScope(context, 'hoi4:write');
-            const progress = progressReporter(extra);
-            await progress.report(0, 3, 'Checking transaction preconditions');
-            const manifest = await engine.transactions.apply(workspaceId, transactionId, expectedPlanHash, {
-                ...(context.principal === undefined ? {} : { principal: context.principal }),
-                signal: progress.signal,
-                postValidate: (transaction, signal) => postValidateTransaction(engine, transaction, context.principal, signal),
-            });
-            engine.invalidate(workspaceId);
-            await engine.scan(workspaceId, {}, context.principal, progress.signal);
-            await progress.report(3, 3, 'Apply and index rebuild complete');
-            const result = emptyServiceResult(workspaceId, {
-                state: manifest.state,
-                fileCount: manifest.files.length,
-                appliedFileCount: manifest.appliedFiles.length,
-                artifactCount: manifest.artifacts.length,
-            });
-            result.code = 'TRANSACTION_APPLIED';
-            result.transactionId = manifest.transactionId;
-            result.planHash = manifest.planHash;
-            result.proposedFiles = manifest.files.slice(0, 100).map(({ relativePath }) => relativePath);
-            result.changedFiles = manifest.appliedFiles.slice(0, 100);
-            result.artifacts = [transactionResourceLink(manifest)];
-            result.validation = manifest.validation;
-            result.rollbackStatus = manifest.rollbackStatus;
-            return toolResult(result);
-        }
-        catch (error) {
-            engine.invalidate(workspaceId);
+            catch (error) {
+                return errorResult(error, workspaceId);
+            }
+        });
+        server.registerTool('hoi4.transaction_apply', {
+            title: 'Apply reviewed transaction',
+            description: 'Apply a completed dry run only when transaction ID, workspace, principal, source hashes, and expected plan hash still match.',
+            inputSchema: transactionInput,
+            outputSchema: transactionMutationOutputSchema,
+            annotations: {
+                readOnlyHint: false,
+                destructiveHint: true,
+                idempotentHint: false,
+                openWorldHint: false,
+            },
+        }, async ({ workspaceId, transactionId, expectedPlanHash }, extra) => {
             try {
-                const failed = await engine.transactions.status(workspaceId, transactionId, context.principal);
-                return errorResult(error, workspaceId, {
-                    transactionId: failed.transactionId,
-                    planHash: failed.planHash,
-                    proposedFiles: failed.files.slice(0, 100).map(({ relativePath }) => relativePath),
-                    changedFiles: failed.state === 'applied' ? failed.appliedFiles.slice(0, 100) : [],
-                    artifacts: [transactionResourceLink(failed)],
-                    validation: failed.validation,
-                    rollbackStatus: failed.rollbackStatus,
-                    data: { state: failed.state, failure: failed.failure ?? null },
+                requireServerScope(context, 'hoi4:write');
+                const progress = progressReporter(extra);
+                await progress.report(0, 3, 'Checking transaction preconditions');
+                const manifest = await engine.transactions.apply(workspaceId, transactionId, expectedPlanHash, {
+                    ...(context.principal === undefined ? {} : { principal: context.principal }),
+                    signal: progress.signal,
+                    postValidate: (transaction, signal) => postValidateTransaction(engine, transaction, context.principal, signal),
+                });
+                engine.invalidate(workspaceId);
+                await engine.scan(workspaceId, {}, context.principal, progress.signal);
+                await progress.report(3, 3, 'Apply and index rebuild complete');
+                const result = emptyServiceResult(workspaceId, {
+                    state: manifest.state,
+                    fileCount: manifest.files.length,
+                    appliedFileCount: manifest.appliedFiles.length,
+                    artifactCount: manifest.artifacts.length,
                 });
+                result.code = 'TRANSACTION_APPLIED';
+                result.transactionId = manifest.transactionId;
+                result.planHash = manifest.planHash;
+                result.proposedFiles = manifest.files
+                    .slice(0, 100)
+                    .map(({ relativePath }) => relativePath);
+                result.changedFiles = manifest.appliedFiles.slice(0, 100);
+                result.artifacts = [transactionResourceLink(manifest)];
+                result.validation = manifest.validation;
+                result.rollbackStatus = manifest.rollbackStatus;
+                return toolResult(result);
             }
-            catch {
-                // A forged or cross-workspace transaction ID intentionally reveals no manifest details.
+            catch (error) {
+                engine.invalidate(workspaceId);
+                try {
+                    const failed = await engine.transactions.status(workspaceId, transactionId, context.principal);
+                    return errorResult(error, workspaceId, {
+                        transactionId: failed.transactionId,
+                        planHash: failed.planHash,
+                        proposedFiles: failed.files.slice(0, 100).map(({ relativePath }) => relativePath),
+                        changedFiles: failed.state === 'applied' ? failed.appliedFiles.slice(0, 100) : [],
+                        artifacts: [transactionResourceLink(failed)],
+                        validation: failed.validation,
+                        rollbackStatus: failed.rollbackStatus,
+                        data: { state: failed.state, failure: failed.failure ?? null },
+                    });
+                }
+                catch {
+                    // A forged or cross-workspace transaction ID intentionally reveals no manifest details.
+                }
+                return errorResult(error, workspaceId);
             }
-            return errorResult(error, workspaceId);
-        }
-    });
-    server.registerTool('hoi4.transaction_rollback', {
-        title: 'Roll back applied transaction',
-        description: 'Restore exact original bytes when the applied result still matches rollback preconditions.',
-        inputSchema: transactionInput,
-        outputSchema: transactionMutationOutputSchema,
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: true,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    }, async ({ workspaceId, transactionId, expectedPlanHash }, extra) => {
-        try {
-            requireServerScope(context, 'hoi4:write');
-            const progress = progressReporter(extra);
-            await progress.report(0, 2, 'Checking rollback preconditions');
-            progress.signal.throwIfAborted();
-            const manifest = await engine.transactions.rollback(workspaceId, transactionId, expectedPlanHash, context.principal, progress.signal);
-            engine.invalidate(workspaceId);
-            const result = emptyServiceResult(workspaceId, {
-                state: manifest.state,
-                fileCount: manifest.files.length,
-                appliedFileCount: manifest.appliedFiles.length,
-                artifactCount: manifest.artifacts.length,
-            });
-            result.code = 'TRANSACTION_ROLLED_BACK';
-            result.transactionId = manifest.transactionId;
-            result.planHash = manifest.planHash;
-            result.changedFiles = manifest.files.slice(0, 100).map(({ relativePath }) => relativePath);
-            result.artifacts = [transactionResourceLink(manifest)];
-            result.validation = manifest.validation;
-            result.rollbackStatus = manifest.rollbackStatus;
-            await progress.report(2, 2, 'Atomic rollback complete');
-            return toolResult(result);
-        }
-        catch (error) {
+        });
+        server.registerTool('hoi4.transaction_rollback', {
+            title: 'Roll back applied transaction',
+            description: 'Restore exact original bytes when the applied result still matches rollback preconditions.',
+            inputSchema: transactionInput,
+            outputSchema: transactionMutationOutputSchema,
+            annotations: {
+                readOnlyHint: false,
+                destructiveHint: true,
+                idempotentHint: false,
+                openWorldHint: false,
+            },
+        }, async ({ workspaceId, transactionId, expectedPlanHash }, extra) => {
             try {
-                const failed = await engine.transactions.status(workspaceId, transactionId, context.principal);
-                return errorResult(error, workspaceId, {
-                    transactionId: failed.transactionId,
-                    planHash: failed.planHash,
-                    proposedFiles: failed.files.slice(0, 100).map(({ relativePath }) => relativePath),
-                    changedFiles: failed.state === 'applied' ? failed.appliedFiles.slice(0, 100) : [],
-                    artifacts: [transactionResourceLink(failed)],
-                    validation: failed.validation,
-                    rollbackStatus: failed.rollbackStatus,
-                    data: { state: failed.state, failure: failed.failure ?? null },
+                requireServerScope(context, 'hoi4:write');
+                const progress = progressReporter(extra);
+                await progress.report(0, 2, 'Checking rollback preconditions');
+                progress.signal.throwIfAborted();
+                const manifest = await engine.transactions.rollback(workspaceId, transactionId, expectedPlanHash, context.principal, progress.signal);
+                engine.invalidate(workspaceId);
+                const result = emptyServiceResult(workspaceId, {
+                    state: manifest.state,
+                    fileCount: manifest.files.length,
+                    appliedFileCount: manifest.appliedFiles.length,
+                    artifactCount: manifest.artifacts.length,
                 });
+                result.code = 'TRANSACTION_ROLLED_BACK';
+                result.transactionId = manifest.transactionId;
+                result.planHash = manifest.planHash;
+                result.changedFiles = manifest.files
+                    .slice(0, 100)
+                    .map(({ relativePath }) => relativePath);
+                result.artifacts = [transactionResourceLink(manifest)];
+                result.validation = manifest.validation;
+                result.rollbackStatus = manifest.rollbackStatus;
+                await progress.report(2, 2, 'Atomic rollback complete');
+                return toolResult(result);
             }
-            catch {
-                // Invalid or inaccessible transaction IDs intentionally reveal no manifest details.
+            catch (error) {
+                try {
+                    const failed = await engine.transactions.status(workspaceId, transactionId, context.principal);
+                    return errorResult(error, workspaceId, {
+                        transactionId: failed.transactionId,
+                        planHash: failed.planHash,
+                        proposedFiles: failed.files.slice(0, 100).map(({ relativePath }) => relativePath),
+                        changedFiles: failed.state === 'applied' ? failed.appliedFiles.slice(0, 100) : [],
+                        artifacts: [transactionResourceLink(failed)],
+                        validation: failed.validation,
+                        rollbackStatus: failed.rollbackStatus,
+                        data: { state: failed.state, failure: failed.failure ?? null },
+                    });
+                }
+                catch {
+                    // Invalid or inaccessible transaction IDs intentionally reveal no manifest details.
+                }
+                return errorResult(error, workspaceId);
             }
-            return errorResult(error, workspaceId);
-        }
-    });
+        });
+    }
     server.registerTool('hoi4.artifact_list', {
         title: 'List workspace artifacts',
         description: 'List content-addressed artifacts without exposing filesystem paths.',