hoi4-agent-tools 2.8.0 → 2.8.1

package/CHANGELOG.md

@@ -4,6 +4,10 @@
 
 No unreleased changes.
 
+## 2.8.1 - 2026-08-27
+
+- Added periodic MCP progress heartbeats for long GUI inspections, renders, and rewrites, with repeated progress notifications that preserve monotonic work values and still honor cancellation.
+
 ## 2.8.0 - 2026-08-26
 
 - Added structured `ROOT`, `THIS`, `PREV`, `FROM` chain, saved-scope, and event-target bindings to probability scenarios.

package/dist/hoi4_agent_tools/mcp/server/create.js

@@ -8,7 +8,7 @@ import { registerEventTools } from '../tools/event.js';
 import { registerTechnologyTools } from '../tools/technology.js';
 import { registerProbabilityTools } from '../tools/probability.js';
 import { registerMcpResources } from '../resources/register.js';
-export const SERVER_INSTRUCTIONS = 'Use focus tools for focus trees, GUI tools for interfaces, and map tools for map data. Start unfamiliar event chains with hoi4.event_inspect. Event tools are read-only. Start technology and doctrine work with hoi4.tech_inspect. Technology tools are read-only. Start weighted AI, MTTH, random, and declared-pool analysis with hoi4.probability_inspect. Probability tools are read-only. Large evidence is linked as resources.';
+export const SERVER_INSTRUCTIONS = 'Use focus tools for focus trees, GUI tools for interfaces, and map tools for map data. Start unfamiliar event chains with hoi4.event_inspect. Event tools are read-only. Start technology and doctrine work with hoi4.tech_inspect. Technology tools are read-only. Start weighted AI, MTTH, random, and declared-pool analysis with hoi4.probability_inspect. Probability tools are read-only. Long GUI calls emit periodic progress heartbeats when the client requests progress. Large evidence is linked as resources.';
 export function createMcpServer(engine, context = {}) {
     const server = new McpServer({
         name: PACKAGE_NAME,

package/dist/hoi4_agent_tools/mcp/server/progress.js

@@ -1,9 +1,18 @@
+/**
+ * Interval used for long-running MCP operations. It is shorter than the request timeout used by
+ * common MCP clients, while still keeping notification traffic negligible for ordinary calls.
+ */
+export const PROGRESS_HEARTBEAT_INTERVAL_MS = 10_000;
 export function progressReporter(extra) {
     let latest = Number.NEGATIVE_INFINITY;
+    let latestTotal = 1;
+    let latestMessage = '';
     return {
         signal: extra.signal,
         async report(progress, total, message) {
             extra.signal.throwIfAborted();
+            latestTotal = total;
+            latestMessage = message;
             const normalized = Math.max(latest, Math.min(progress, total));
             const progressToken = extra._meta?.progressToken;
             if (progressToken === undefined)
@@ -16,5 +25,53 @@ export function progressReporter(extra) {
                 params: { progressToken, progress: normalized, total, message },
             });
         },
+        async pulse(message = latestMessage) {
+            extra.signal.throwIfAborted();
+            const progressToken = extra._meta?.progressToken;
+            if (progressToken === undefined)
+                return;
+            await extra.sendNotification({
+                method: 'notifications/progress',
+                params: {
+                    progressToken,
+                    progress: Number.isFinite(latest) ? latest : 0,
+                    total: latestTotal,
+                    message,
+                },
+            });
+        },
+    };
+}
+/**
+ * Keep an MCP request alive while a domain service is in a long, opaque asynchronous stage.
+ * Progress notifications are best-effort: a disconnected client must not turn a successful
+ * server operation into a partial result, while the request's AbortSignal still cancels work.
+ */
+export async function withProgressHeartbeat(operation, reporter, message, intervalMs = PROGRESS_HEARTBEAT_INTERVAL_MS) {
+    if (!Number.isFinite(intervalMs) || intervalMs <= 0) {
+        throw new RangeError('Progress heartbeat interval must be a positive finite number');
+    }
+    reporter.signal.throwIfAborted();
+    let active = true;
+    let inFlight = false;
+    const tick = () => {
+        if (!active || inFlight || reporter.signal.aborted)
+            return;
+        inFlight = true;
+        void reporter
+            .pulse(message)
+            .catch(() => undefined)
+            .finally(() => {
+            inFlight = false;
+        });
     };
+    const timer = setInterval(tick, intervalMs);
+    timer.unref();
+    try {
+        return await (typeof operation === 'function' ? operation() : operation);
+    }
+    finally {
+        active = false;
+        clearInterval(timer);
+    }
 }

package/dist/hoi4_agent_tools/mcp/tools/gui.js

@@ -12,7 +12,7 @@ import { requireServerScope, resolveServerWorkspaceId, } from '../server/base-to
 import { compactValidatedInputSchema } from '../server/context-schemas.js';
 import { autonomousFailureContext, autonomousResultArtifacts, executePlannedTransaction, } from '../server/transaction-execution.js';
 import { indexSkippedSourceSchema, nonNegativeIntegerSchema, sha256Schema, } from '../server/output-schemas.js';
-import { progressReporter } from '../server/progress.js';
+import { progressReporter, withProgressHeartbeat } from '../server/progress.js';
 import { errorResult, setInlineFilesScanned, strictOperationResultSchema, toolResult, } from '../server/result.js';
 const countRecordSchema = z.record(z.string().max(256), nonNegativeIntegerSchema);
 const guiScanOutputSchema = strictOperationResultSchema(z
@@ -156,21 +156,21 @@ export function registerGuiTools(server, engine, context) {
         try {
             const progress = progressReporter(extra);
             await progress.report(0, 3, 'Building GUI source graph');
-            const inspection = windowName === undefined || scenario === undefined
-                ? studio
-                    .scan(workspaceId, context.principal, progress.signal)
-                    .then(({ graph }) => ({ graph, linted: undefined }))
-                : studio
-                    .lint({
+            const inspected = await withProgressHeartbeat(async () => {
+                if (windowName === undefined || scenario === undefined) {
+                    const { graph } = await studio.scan(workspaceId, context.principal, progress.signal);
+                    return { graph, linted: undefined };
+                }
+                const linted = await studio.lint({
                     workspaceId,
                     windowName,
                     scenario,
                     ...(relatedScenarios === undefined ? {} : { relatedScenarios }),
                     ...(context.principal === undefined ? {} : { principal: context.principal }),
                     signal: progress.signal,
-                })
-                    .then((linted) => ({ graph: linted.graph, linted }));
-            const inspected = await inspection;
+                });
+                return { graph: linted.graph, linted };
+            }, progress, 'Inspecting GUI sources and linked assets');
             const { graph, linted } = inspected;
             const sharedRevision = hashCanonical(graph.sourceHashes);
             const workspace = engine.resolver.get(workspaceId, context.principal);
@@ -268,7 +268,7 @@ export function registerGuiTools(server, engine, context) {
         try {
             const progress = progressReporter(extra);
             await progress.report(0, 4, 'Building GUI source graph');
-            const rendered = await studio.renderAndStore({
+            const rendered = await withProgressHeartbeat(() => studio.renderAndStore({
                 workspaceId,
                 windowName,
                 scenario: input.scenario,
@@ -290,7 +290,7 @@ export function registerGuiTools(server, engine, context) {
                     : { comparisonScenario: input.comparisonScenario }),
                 ...(context.principal === undefined ? {} : { principal: context.principal }),
                 signal: progress.signal,
-            });
+            }), progress, 'Rendering GUI variants and visual diagnostics');
             await progress.report(3, 4, 'Preparing GUI result');
             const diagnostics = rendered.validation.diagnostics;
             const result = emptyServiceResult(workspaceId, {
@@ -471,7 +471,7 @@ export function registerGuiTools(server, engine, context) {
             const progress = progressReporter(extra);
             await progress.report(0, 3, 'Validating the requested GUI result');
             const compilation = input.mode === 'helpers' ? compileGuiHelpers(input.helper) : undefined;
-            const plannedTransaction = await studio.planSource({
+            const plannedTransaction = await withProgressHeartbeat(() => studio.planSource({
                 workspaceId,
                 relativePath,
                 ...(input.mode === 'patches'
@@ -489,9 +489,9 @@ export function registerGuiTools(server, engine, context) {
                 scenario,
                 ...(context.principal === undefined ? {} : { principal: context.principal }),
                 signal: progress.signal,
-            });
+            }), progress, 'Preparing GUI rewrite');
             await progress.report(2, 3, 'Applying and validating the GUI rewrite');
-            const execution = await executePlannedTransaction(engine, plannedTransaction, context.principal, progress.signal);
+            const execution = await withProgressHeartbeat(() => executePlannedTransaction(engine, plannedTransaction, context.principal, progress.signal), progress, 'Applying GUI rewrite');
             const transaction = execution.transaction;
             const planned = {
                 transaction,

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.8.0';
+export const PACKAGE_VERSION = '2.8.1';
 export const MCP_PROTOCOL_VERSION = LATEST_PROTOCOL_VERSION;
 export const CONFIG_VERSION = 1;
 export const TRANSACTION_VERSION = 1;

package/docs/gui.md

@@ -58,6 +58,8 @@ Broad inspection indexes localisation actually referenced by GUI source and retu
 
 GUI rewrites keep complete validation evidence in a linked JSON resource and retain the highest-priority findings in the transaction result. Large surrounding interface inventories therefore do not turn a small scalar patch into a transaction structure-limit error.
 
+Large inspections, renders, and rewrites send periodic MCP progress heartbeats while a service stage is still running. Clients that request progress can reset their idle request timer from these notifications; there is no 180-second GUI operation limit in the server, and cancellation still follows the request signal.
+
 ## Offline preview limits
 
 The renderer does not run the game engine. Each render includes a fidelity report that separates fields it models from fields it approximates, ignores, cannot resolve, or does not support. Treat that report as part of the review.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hoi4-agent-tools",
   "mcpName": "io.github.klimPaskov/hoi4-agent-tools",
-  "version": "2.8.0",
+  "version": "2.8.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.8.0/schemas/configuration.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.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.8.0/schemas/continuous-focus-palette.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.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.8.0/schemas/custom-weighted-pool.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.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.8.0/schemas/event-feature-manifest.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.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.8.0/schemas/focus-plan.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.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.8.0/schemas/focus-planning-sidecar.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.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.8.0/schemas/gui-animation-source.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.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.8.0/schemas/gui-helper.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.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.8.0/schemas/gui-scenario.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.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.8.0/schemas/map-operation.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.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.8.0/schemas/operation-result.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.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.8.0/schemas/probability-analysis-result.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.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.8.0/schemas/probability-compare-input.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.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.8.0/schemas/probability-evaluate-input.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.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.8.0/schemas/probability-inspect-input.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.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.8.0/schemas/probability-render-input.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.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.8.0/schemas/probability-scenario-set.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.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.8.0/schemas/probability-sequence-input.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.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.8.0/schemas/probability-simulate-input.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.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.8.0/schemas/probability-sweep-input.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.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.8.0",
+  "version": "2.8.1",
   "repository": {
     "url": "https://github.com/klimPaskov/hoi4-agent-tools",
     "source": "github"
@@ -13,7 +13,7 @@
     {
       "registryType": "npm",
       "identifier": "hoi4-agent-tools",
-      "version": "2.8.0",
+      "version": "2.8.1",
       "transport": {
         "type": "stdio"
       }