hoi4-agent-tools 2.5.0 → 2.5.1

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 2.5.1 - 2026-08-13
+
+- Published artifact contents and provenance manifests atomically across independent MCP processes, preventing event, probability, GUI, and other concurrent inspections from observing partially written manifests.
+- Recovered clearly interrupted zero-filled or truncated provenance manifests during matching writes and storage pruning while continuing to reject arbitrary malformed or tampered manifests.
+- Tolerated temporary-file disappearance during concurrent storage scans without weakening artifact integrity validation.
+- Added cross-process publication, interrupted-write recovery, and fail-closed integrity regressions, then verified event inspection, probability inspection, and artifact-resource workflows against the repaired store.
+
 ## 2.5.0 - 2026-08-09
 
 - Added exact continuous-focus coordinates and linked palette IDs to compact national focus inspection results.

package/dist/hoi4_agent_tools/core/artifacts.js

@@ -1,5 +1,5 @@
-import { createHash } from 'node:crypto';
-import { lstat, mkdir, open, readFile, readdir, stat, unlink, writeFile } from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import { link, lstat, mkdir, open, readFile, readdir, stat, unlink } from 'node:fs/promises';
 import path from 'node:path';
 import { z } from 'zod/v4';
 import { canonicalJson, compareCodeUnits, sha256Bytes } from './canonical.js';
@@ -159,6 +159,8 @@ const artifactManifestMaxBytes = 1_048_576;
 const artifactLogicalBatchMaxBytes = 536_870_912;
 const artifactHashYieldBytes = 16_777_216;
 const artifactPreflightYieldEntries = 256;
+const interruptedManifestMinimumAgeMs = 1_000;
+const artifactTemporaryPrefix = '.artifact-tmp-';
 const ownedArtifactContent = Symbol('ownedArtifactContent');
 const precomputedArtifactSha256 = Symbol('precomputedArtifactSha256');
 export const chunkedArtifactIndexMimeType = 'application/json';
@@ -320,11 +322,22 @@ async function artifactUsage(root, signal) {
             if (child.isSymbolicLink()) {
                 throw new ServiceError('ARTIFACT_STORAGE_UNSAFE', 'Artifact storage contains a symbolic link or junction');
             }
+            if (child.isFile() && child.name.startsWith(artifactTemporaryPrefix))
+                continue;
             const candidate = await containedGeneratedPath(root, path.relative(root, path.join(directory, child.name)));
             if (child.isDirectory())
                 await walk(candidate);
             else if (child.isFile()) {
-                bytes += (await stat(candidate)).size;
+                let size;
+                try {
+                    size = (await stat(candidate)).size;
+                }
+                catch (error) {
+                    if (error.code === 'ENOENT')
+                        continue;
+                    throw error;
+                }
+                bytes += size;
                 if (child.name.endsWith('.manifest.json'))
                     entries += 1;
                 if (!Number.isSafeInteger(bytes)) {
@@ -375,6 +388,101 @@ async function readArtifactManifest(filePath, signal) {
         throw new ServiceError('ARTIFACT_MANIFEST_INVALID', 'Artifact provenance manifest is invalid');
     }
 }
+async function readBoundedManifestBytes(filePath, signal) {
+    signal?.throwIfAborted();
+    let metadata;
+    try {
+        metadata = await lstat(filePath);
+    }
+    catch {
+        throw new ServiceError('ARTIFACT_NOT_FOUND', 'Artifact provenance manifest is unavailable');
+    }
+    if (metadata.isSymbolicLink() || !metadata.isFile()) {
+        throw new ServiceError('ARTIFACT_MANIFEST_INVALID', 'Artifact provenance manifest is invalid');
+    }
+    if (metadata.size > artifactManifestMaxBytes) {
+        throw new ServiceError('ARTIFACT_MANIFEST_LIMIT', 'Artifact provenance manifest exceeds its fixed byte limit');
+    }
+    try {
+        const bytes = signal === undefined ? await readFile(filePath) : await readFile(filePath, { signal });
+        return { bytes, metadata };
+    }
+    catch (error) {
+        if (error.name === 'AbortError')
+            throw error;
+        throw new ServiceError('ARTIFACT_NOT_FOUND', 'Artifact provenance manifest is unavailable');
+    }
+}
+function zeroFilled(bytes) {
+    return bytes.length === 0 || bytes.every((value) => value === 0);
+}
+async function interruptedManifestState(filePath, expectedBytes, signal) {
+    const { bytes, metadata } = await readBoundedManifestBytes(filePath, signal);
+    const expected = expectedBytes === undefined ? undefined : Buffer.from(expectedBytes, 'utf8');
+    const expectedPrefix = expected !== undefined &&
+        bytes.length < expected.length &&
+        expected.subarray(0, bytes.length).equals(bytes);
+    const staleZeroFill = zeroFilled(bytes) && Date.now() - Number(metadata.mtimeMs) >= interruptedManifestMinimumAgeMs;
+    return { interrupted: expectedPrefix || staleZeroFill, size: Number(metadata.size) };
+}
+async function existingManifestMatches(filePath, expectedBytes, signal) {
+    if (!(await fileExists(filePath)))
+        return false;
+    try {
+        const manifest = await readArtifactManifest(filePath, signal);
+        if (`${canonicalJson(manifest)}\n` !== expectedBytes) {
+            throw new ServiceError('ARTIFACT_MANIFEST_INTEGRITY_FAILED', 'Immutable artifact provenance manifest contains different bytes');
+        }
+        return true;
+    }
+    catch (error) {
+        if (error instanceof ServiceError && error.code === 'ARTIFACT_NOT_FOUND')
+            return false;
+        if (!(error instanceof ServiceError) || error.code !== 'ARTIFACT_MANIFEST_INVALID')
+            throw error;
+        const state = await interruptedManifestState(filePath, expectedBytes, signal);
+        if (!state.interrupted)
+            throw error;
+        try {
+            await unlink(filePath);
+        }
+        catch (unlinkError) {
+            if (unlinkError.code !== 'ENOENT')
+                throw unlinkError;
+        }
+        return false;
+    }
+}
+async function publishExclusiveFile(target, bytes, signal) {
+    signal?.throwIfAborted();
+    const temporary = path.join(path.dirname(target), `${artifactTemporaryPrefix}${process.pid}-${randomUUID().replaceAll('-', '')}`);
+    let handle;
+    try {
+        handle = await open(temporary, 'wx');
+        await handle.writeFile(bytes, signal === undefined ? undefined : { signal });
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        signal?.throwIfAborted();
+        try {
+            await link(temporary, target);
+            return true;
+        }
+        catch (error) {
+            if (error.code === 'EEXIST')
+                return false;
+            throw error;
+        }
+    }
+    finally {
+        if (handle !== undefined)
+            await handle.close().catch(() => undefined);
+        await unlink(temporary).catch((error) => {
+            if (error.code !== 'ENOENT')
+                throw error;
+        });
+    }
+}
 async function readVerifiedArtifactRange(filePath, expectedSha256, range, verifiedIdentity, signal) {
     signal?.throwIfAborted();
     if (range !== undefined &&
@@ -495,8 +603,47 @@ export class ArtifactStore {
                 }
                 if (!child.isFile() || !child.name.endsWith('.manifest.json'))
                     continue;
-                const metadata = await lstat(candidate);
-                const manifest = await readArtifactManifest(candidate, signal);
+                let metadata;
+                try {
+                    metadata = await lstat(candidate);
+                }
+                catch (error) {
+                    if (error.code === 'ENOENT')
+                        continue;
+                    throw error;
+                }
+                let manifest;
+                try {
+                    manifest = await readArtifactManifest(candidate, signal);
+                }
+                catch (error) {
+                    if (error instanceof ServiceError && error.code === 'ARTIFACT_NOT_FOUND')
+                        continue;
+                    if (!(error instanceof ServiceError) || error.code !== 'ARTIFACT_MANIFEST_INVALID')
+                        throw error;
+                    let interrupted;
+                    try {
+                        interrupted = await interruptedManifestState(candidate, undefined, signal);
+                    }
+                    catch (interruptedError) {
+                        if (interruptedError instanceof ServiceError &&
+                            interruptedError.code === 'ARTIFACT_NOT_FOUND')
+                            continue;
+                        throw interruptedError;
+                    }
+                    if (!interrupted.interrupted)
+                        throw error;
+                    try {
+                        await unlink(candidate);
+                    }
+                    catch (unlinkError) {
+                        if (unlinkError.code !== 'ENOENT')
+                            throw unlinkError;
+                    }
+                    usage.entries = Math.max(0, usage.entries - 1);
+                    usage.bytes = Math.max(0, usage.bytes - interrupted.size);
+                    continue;
+                }
                 if (child.name !== `${manifest.name}.${manifest.provenanceHash}.manifest.json`) {
                     throw new ServiceError('ARTIFACT_MANIFEST_INTEGRITY_FAILED', 'Artifact provenance manifest filename does not match its contents');
                 }
@@ -993,13 +1140,8 @@ export class ArtifactStore {
                     throw new ServiceError('ARTIFACT_MANIFEST_INTEGRITY_FAILED', 'Artifact batch maps different provenance to the same immutable manifest');
                 }
                 if (duplicateManifest === undefined) {
-                    const exists = await fileExists(artifact.manifestPath);
+                    const exists = await existingManifestMatches(artifact.manifestPath, artifact.manifestBytes, signal);
                     signal?.throwIfAborted();
-                    if (exists &&
-                        `${canonicalJson(await readArtifactManifest(artifact.manifestPath, signal))}\n` !==
-                            artifact.manifestBytes) {
-                        throw new ServiceError('ARTIFACT_MANIFEST_INTEGRITY_FAILED', 'Immutable artifact provenance manifest contains different bytes');
-                    }
                     uniqueManifests.set(artifact.manifestPath, { ...artifact, exists });
                 }
             }
@@ -1020,18 +1162,19 @@ export class ArtifactStore {
                         continue;
                     await mkdir(artifact.directory, { recursive: true });
                     signal?.throwIfAborted();
-                    try {
-                        await writeFile(artifact.target, artifact.bytes, {
-                            flag: 'wx',
-                            ...(signal === undefined ? {} : { signal }),
-                        });
+                    const created = await publishExclusiveFile(artifact.target, artifact.bytes, signal);
+                    if (created) {
                         createdTargets.push(artifact.target);
                     }
-                    catch (error) {
-                        if (error.code !== 'EEXIST') {
-                            createdTargets.push(artifact.target);
+                    else {
+                        try {
+                            await readVerifiedArtifactRange(artifact.target, artifact.artifact.sha256, { offset: 0, length: 1 }, undefined, signal);
+                        }
+                        catch (error) {
+                            if (error.name === 'AbortError')
+                                throw error;
+                            throw new ServiceError('ARTIFACT_HASH_COLLISION', 'Artifact path contains different bytes');
                         }
-                        throw error;
                     }
                 }
                 for (const artifact of uniqueManifests.values()) {
@@ -1040,18 +1183,12 @@ export class ArtifactStore {
                         continue;
                     await mkdir(artifact.directory, { recursive: true });
                     signal?.throwIfAborted();
-                    try {
-                        await writeFile(artifact.manifestPath, artifact.manifestBytes, {
-                            flag: 'wx',
-                            ...(signal === undefined ? {} : { signal }),
-                        });
+                    const created = await publishExclusiveFile(artifact.manifestPath, artifact.manifestBytes, signal);
+                    if (created) {
                         createdManifests.push(artifact.manifestPath);
                     }
-                    catch (error) {
-                        if (error.code !== 'EEXIST') {
-                            createdManifests.push(artifact.manifestPath);
-                        }
-                        throw error;
+                    else if (!(await existingManifestMatches(artifact.manifestPath, artifact.manifestBytes, signal))) {
+                        throw new ServiceError('ARTIFACT_MANIFEST_INVALID', 'Concurrent artifact provenance manifest publication did not complete');
                     }
                 }
                 signal?.throwIfAborted();

package/dist/hoi4_agent_tools/version.js

@@ -1,6 +1,6 @@
 import { LATEST_PROTOCOL_VERSION } from '@modelcontextprotocol/sdk/types.js';
 export const PACKAGE_NAME = 'hoi4-agent-tools';
-export const PACKAGE_VERSION = '2.5.0';
+export const PACKAGE_VERSION = '2.5.1';
 export const MCP_PROTOCOL_VERSION = LATEST_PROTOCOL_VERSION;
 export const CONFIG_VERSION = 1;
 export const TRANSACTION_VERSION = 1;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hoi4-agent-tools",
   "mcpName": "io.github.klimPaskov/hoi4-agent-tools",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "description": "Analyze HOI4 events, tech trees, AI weights, and MTTH; build focus trees, GUIs, and maps.",
   "type": "module",
   "license": "Apache-2.0",

package/schemas/configuration.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.0/schemas/configuration.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.1/schemas/configuration.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/continuous-focus-palette.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.0/schemas/continuous-focus-palette.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.1/schemas/continuous-focus-palette.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/custom-weighted-pool.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.0/schemas/custom-weighted-pool.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.1/schemas/custom-weighted-pool.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/event-feature-manifest.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.0/schemas/event-feature-manifest.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.1/schemas/event-feature-manifest.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/focus-plan.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.0/schemas/focus-plan.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.1/schemas/focus-plan.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/focus-planning-sidecar.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.0/schemas/focus-planning-sidecar.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.1/schemas/focus-planning-sidecar.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/gui-animation-source.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.0/schemas/gui-animation-source.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.1/schemas/gui-animation-source.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/gui-helper.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.0/schemas/gui-helper.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.1/schemas/gui-helper.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/gui-scenario.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.0/schemas/gui-scenario.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.1/schemas/gui-scenario.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/map-operation.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.0/schemas/map-operation.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.1/schemas/map-operation.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "oneOf": [
     {

package/schemas/operation-result.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.0/schemas/operation-result.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.1/schemas/operation-result.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/probability-analysis-result.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.0/schemas/probability-analysis-result.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.1/schemas/probability-analysis-result.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/probability-compare-input.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.0/schemas/probability-compare-input.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.1/schemas/probability-compare-input.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/probability-evaluate-input.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.0/schemas/probability-evaluate-input.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.1/schemas/probability-evaluate-input.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/probability-inspect-input.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.0/schemas/probability-inspect-input.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.1/schemas/probability-inspect-input.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/probability-render-input.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.0/schemas/probability-render-input.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.1/schemas/probability-render-input.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/probability-scenario-set.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.0/schemas/probability-scenario-set.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.1/schemas/probability-scenario-set.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/probability-sequence-input.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.0/schemas/probability-sequence-input.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.1/schemas/probability-sequence-input.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/probability-simulate-input.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.0/schemas/probability-simulate-input.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.1/schemas/probability-simulate-input.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/probability-sweep-input.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.0/schemas/probability-sweep-input.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.1/schemas/probability-sweep-input.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.klimPaskov/hoi4-agent-tools",
   "title": "HOI4 Agent Tools",
   "description": "Analyze HOI4 events, tech trees, AI weights, and MTTH; build focus trees, GUIs, and maps.",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "repository": {
     "url": "https://github.com/klimPaskov/hoi4-agent-tools",
     "source": "github"
@@ -13,7 +13,7 @@
     {
       "registryType": "npm",
       "identifier": "hoi4-agent-tools",
-      "version": "2.5.0",
+      "version": "2.5.1",
       "transport": {
         "type": "stdio"
       }