hoi4-agent-tools 4.0.1 → 4.0.4

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## Unreleased
 
+## 4.0.4 - 2026-10-14
+
+- Preview individual GUI windows without redundant full symbol indexes, workspace-wide asset fallback or unbound country-flag inventories; reuse condition definitions across render variants.
+- Index technology sources once across layers and scope folder rendering to definitions, layouts and unlock targets. Full inspection retains inbound grants and references.
+- Report render phases and include the last phase in worker deadline errors. Existing parsing, raster-memory, canonical-path and stale-source limits remain enforced.
+- Resolve transitive localisation `$KEY$` references across files and bounded scenario substitutions; retain diagnostics for cycles and missing runtime values.
+- Honour numeric flag presence in scalar visibility checks, matching valued-flag super-event localisation conditions.
+- Preserve supplied GUI scenarios by default; exploratory `generatedScenarios` is now opt-in. Explicit state/resolution matrices and public schema shapes are unchanged.
+- Retain regression coverage for hidden sub-windows, timed animated-sprite frames, 16-bit DDS portraits, declared font colours, worker recovery and render-memory ceilings.
+
+## 4.0.3 - 2026-10-12
+
+- Publish the README with the supplied HOI4 MCP Server thumbnail and direct links to the demo video on YouTube.
+- Include the exact install command in the authored release page. Server behavior, tool schema shapes and dependency versions are unchanged from 4.0.1.
+
+## 4.0.2 - 2026-10-12
+
+Not published: release validation stopped before publication because the authored page omitted its install command.
+
+- Put the published demo video first in the README, using the supplied HOI4 MCP Server thumbnail and a direct link to the YouTube video.
+- Use a public image URL so the thumbnail also loads on the npm package page.
+- Documentation and release metadata only; server behavior, tool schemas and dependency versions are unchanged.
+
 ## 4.0.1 - 2026-10-12
 
 - Clean temporary test fixtures after each test, suite teardown and normal process exit. Reject fixture truncation above a 256 MiB aggregate disk budget before Windows allocates the file.

package/README.md

@@ -1,8 +1,6 @@
 # HOI4 Agent Tools
 
-<!-- TODO-VIDEO-LINK: replace with the promo video URL -->
-
-[![Watch the HOI4 Agent Tools demo](docs/images/agent-tools-demo-thumbnail.png)](https://www.youtube.com/@ChaosRedux)
+[![Watch the HOI4 Agent Tools demo](https://raw.githubusercontent.com/klimPaskov/hoi4-agent-tools/main/docs/images/agent-tools-demo-thumbnail.png)](https://www.youtube.com/watch?v=Dd36E_NK4rQ)
 
 [![npm](https://img.shields.io/npm/v/hoi4-agent-tools)](https://www.npmjs.com/package/hoi4-agent-tools)
 [![Node.js](https://img.shields.io/node/v/hoi4-agent-tools)](https://nodejs.org/)
@@ -43,7 +41,7 @@ You describe what you want; the agent picks the right tools.
 
 The [setup guide](docs/setup.md) covers several mods, explicit game paths, local wiki snapshots and troubleshooting with `--discover` and `--diagnose`.
 
-[Watch the Agent Tools demo](https://github.com/klimPaskov/Agentic-HOI4-Modding/releases/latest/download/hoi4_agent_tools_promo.mp4) or use [HOI4 Mod Setup](https://github.com/klimPaskov/HOI4-Mod-Setup/releases/latest) to install and connect the server for your mod.
+[Watch the Agent Tools demo](https://www.youtube.com/watch?v=Dd36E_NK4rQ) or use [HOI4 Mod Setup](https://github.com/klimPaskov/HOI4-Mod-Setup/releases/latest) to install and connect the server for your mod.
 Part of the HOI4 modding toolkit with [Agentic HOI4 Modding](https://github.com/klimPaskov/Agentic-HOI4-Modding) (skills and instructions for your agent) and [HOI4 Live Tools](https://github.com/klimPaskov/HOI4-Live-Tools) (testing in the running game).
 
 ## Examples

package/dist/hoi4_agent_tools/core/clausewitz-evaluation.js

@@ -31,11 +31,13 @@ export class ClausewitzEvaluationDefinitions {
     scriptedTriggers = new Map();
     localConstants = new Map();
     static build(snapshot) {
-        const cached = definitionCache.get(snapshot);
+        const cached = definitionCache.get(snapshot.files);
         if (cached !== undefined)
             return cached;
         const result = new ClausewitzEvaluationDefinitions();
-        for (const file of snapshot.files.filter(({ shadowedBy, relativePath }) => shadowedBy === undefined && relativePath.toLowerCase().endsWith('.txt'))) {
+        for (const file of snapshot.files.filter(({ shadowedBy, relativePath, bytes }) => shadowedBy === undefined &&
+            relativePath.toLowerCase().endsWith('.txt') &&
+            bytes.includes(0x40))) {
             const document = parseClausewitz(file.bytes, file.displayPath);
             const locals = new Map();
             for (const assignment of scalarAssignments(document.root)) {
@@ -84,7 +86,7 @@ export class ClausewitzEvaluationDefinitions {
                 });
             }
         }
-        definitionCache.set(snapshot, result);
+        definitionCache.set(snapshot.files, result);
         return result;
     }
 }

package/dist/hoi4_agent_tools/core/condition-evaluator.js

@@ -286,7 +286,11 @@ function evaluateAssignmentCore(assignment, scenario, candidate, definitions, he
             : { state: value ? 'true' : 'false', unresolved: [] };
     }
     if (key === 'has_country_flag' || key === 'has_global_flag' || key === 'has_state_flag') {
-        const explicit = bool(scopeStateValue(scenario, `flag.${right}`, scopeContext));
+        const stored = key === 'has_global_flag'
+            ? (scopeStateValue(scenario, `global_flag.${right}`, scopeContext) ??
+                scopeStateValue(scenario, `flag.${right}`, scopeContext))
+            : scopeStateValue(scenario, `flag.${right}`, scopeContext);
+        const explicit = typeof stored === 'number' && Number.isFinite(stored) ? true : bool(stored);
         if (explicit !== undefined)
             return { state: explicit ? 'true' : 'false', unresolved: [] };
         const flags = key === 'has_global_flag' && scenario.globalFlags !== undefined

package/dist/hoi4_agent_tools/core/index.js

@@ -383,6 +383,17 @@ export class SymbolIndex {
             },
         });
     }
+    /** Record parser coverage without allocating symbols for a domain that builds its own graph. */
+    recordSourceCoverage(file, diagnostics) {
+        const limits = sourcePartialLimitDiagnostics(diagnostics);
+        if (limits.length > 0) {
+            this.recordSkippedSource(file, limits);
+            return false;
+        }
+        if (isWorkspaceOwnedSource(file) && file.shadowedBy === undefined)
+            this.addDiagnostics(diagnostics);
+        return true;
+    }
     addSymbol(record) {
         if (this.symbols.length >= INDEX_RECORD_LIMIT) {
             this.#complete = false;

package/dist/hoi4_agent_tools/core/job-executor.js

@@ -106,10 +106,11 @@ export class JobExecutor {
         const controller = new AbortController();
         const watchStop = new AbortController();
         let watchFailure;
+        let lastProgressMessage = claimed.record.progress?.message;
         const deadlineTimer = options.deadlineMs === undefined || operation.mutation
             ? undefined
             : setTimeout(() => {
-                watchFailure = new ServiceError('JOB_DEADLINE_EXCEEDED', 'The job ran past its deadline and was stopped; narrow its selector or limits, or raise jobDeadlineSeconds');
+                watchFailure = new ServiceError('JOB_DEADLINE_EXCEEDED', `The job ran past its deadline and was stopped${lastProgressMessage === undefined ? '' : ` during: ${lastProgressMessage.slice(0, 160)}`}; narrow its selector or limits, or raise jobDeadlineSeconds`);
                 controller.abort(watchFailure);
             }, Math.max(0, options.deadlineMs - Date.now()));
         const watch = (async () => {
@@ -136,6 +137,7 @@ export class JobExecutor {
             signal: controller.signal,
             checkpoint: claimed.record.checkpoint,
             progress: async (progress) => {
+                lastProgressMessage = progress.message;
                 await this.jobs.store.updateOwned(scope, id, owner.token, { progress }, controller.signal);
             },
             saveCheckpoint: async (checkpoint) => {

package/dist/hoi4_agent_tools/core/job-worker-host.js

@@ -309,7 +309,7 @@ export class JobWorkerHost {
                     await stopChild(child, this.stoppedByHost);
                     await this.jobs.failInterrupted(workspaceId, id, {
                         code: 'JOB_DEADLINE_EXCEEDED',
-                        message: `The job ran longer than ${jobDeadlineSeconds} seconds and was stopped; narrow its selector or limits, or raise jobDeadlineSeconds`,
+                        message: `The job ran longer than ${jobDeadlineSeconds} seconds and was stopped${record.progress === undefined ? '' : ` during: ${record.progress.message.slice(0, 160)}`}; narrow its selector or limits, or raise jobDeadlineSeconds`,
                     }, principal);
                     return;
                 }

package/dist/hoi4_agent_tools/core/render-progress.js

@@ -0,0 +1,7 @@
+export async function renderStage(input, phase) {
+    input.signal?.throwIfAborted();
+    await new Promise((resolve) => setImmediate(resolve));
+    input.signal?.throwIfAborted();
+    await input.progress?.(phase);
+    input.signal?.throwIfAborted();
+}

package/dist/hoi4_agent_tools/gui/layout.js

@@ -219,15 +219,20 @@ function resolveTokenText(value, scenario, localisation, rowValues) {
         /^[A-Za-z0-9_.-]+$/u.test(value) &&
         (value.includes('_') || value === value.toUpperCase()))
         missingLocalisation = true;
-    text = replaceTextBounded(text, /\$([A-Za-z0-9_.-]+)\$/gu, (match) => {
+    const expandTokens = (input, stack, depth) => replaceTextBounded(input, /\$([A-Za-z0-9_.-]+)\$/gu, (match) => {
         const key = match[1] ?? '';
-        const replacement = scenario.localisation[key] ?? localisation.get(key);
-        if (replacement === undefined) {
-            unresolved.push(`$${key}$`);
-            return `$${key}$`;
+        const replacement = scenario.localisation[key] ??
+            localisation.get(key) ??
+            rowValues?.[key] ??
+            scenario.values[key] ??
+            scenario.variables[key];
+        if (replacement === undefined || stack.has(key) || depth >= 16) {
+            unresolved.push(match[0]);
+            return match[0];
         }
-        return replacement;
+        return expandTokens(String(replacement), new Set([...stack, key]), depth + 1);
     }, 'GUI localisation substitution');
+    text = expandTokens(text, new Set([value]), 0);
     text = replaceTextBounded(text, /\[\?([^\]|]+)(?:\|[^\]]+)?\]/gu, (match) => {
         const key = match[1] ?? '';
         const shortKey = key.slice(key.lastIndexOf('.') + 1);
@@ -2026,7 +2031,9 @@ export async function buildGuiScene(graph, scannedFiles, windowName, scenario, c
     const localisation = new Map(graph.localisation
         .filter((entry) => entry.language.toLowerCase() === scenario.language.toLowerCase() ||
         entry.language.toLowerCase() === `l_${scenario.language.toLowerCase()}`)
-        .map((entry) => [entry.key, entry.value]));
+        // Graph localisation is ordered with the active (highest-priority) definition first.
+        .map((entry) => [entry.key, entry.value])
+        .reverse());
     if (localisation.size === 0) {
         for (const entry of graph.localisation)
             if (!localisation.has(entry.key))
@@ -2058,7 +2065,7 @@ export async function buildGuiScene(graph, scannedFiles, windowName, scenario, c
     const countryFlagProperties = new Map();
     const conditionDefinitions = relevantScriptedGuiNames.size === 0
         ? undefined
-        : ClausewitzEvaluationDefinitions.build({ files: [...scannedFiles] });
+        : ClausewitzEvaluationDefinitions.build({ files: scannedFiles });
     const conditionScenario = guiConditionScenario(scenario);
     for (const scripted of graph.scriptedGuis.filter(({ name }) => relevantScriptedGuiNames.has(name))) {
         const source = scannedFiles.find(({ displayPath }) => displayPath === scripted.sourcePath);

package/dist/hoi4_agent_tools/gui/scenario-generator.js

@@ -3,7 +3,7 @@ import { ClausewitzEvaluationDefinitions } from '../core/clausewitz-evaluation.j
 import { evaluateGuiCondition, guiConditionScenario, guiConditionVariables, guiExplicitConditionValues, } from './scenario-conditions.js';
 import { parsePreviewScenario } from './scenario.js';
 const countryNames = ['Germany', 'France', 'Poland', 'Italy', 'Brazil', 'India', 'Canada'];
-const countryTags = ['GER', 'FRA', 'POL', 'ITA', 'BRA', 'RAJ', 'CAN'];
+export const generatedCountryTags = ['GER', 'FRA', 'POL', 'ITA', 'BRA', 'RAJ', 'CAN'];
 const countryIdeologies = [
     'fascism',
     'democratic',
@@ -435,7 +435,7 @@ function generatedRows(count, random, options) {
     return Array.from({ length: count }, (_unused, index) => {
         const countryIndex = (countryOffset + index) % countryNames.length;
         const name = countryNames[countryIndex];
-        const tag = countryTags[countryIndex];
+        const tag = generatedCountryTags[countryIndex];
         const ideology = countryIdeologies[countryIndex];
         const value = generatedNumber(options, random);
         return {
@@ -587,7 +587,7 @@ export function generateGuiPreviewScenarios(graph, windowName, base, options, de
         const elementStates = { ...base.elementStates };
         const scopedCountries = new Map();
         const generatedCountryIndex = random.integer(0, countryNames.length - 1);
-        const generatedCountryTag = countryTags[generatedCountryIndex];
+        const generatedCountryTag = generatedCountryTags[generatedCountryIndex];
         for (const key of tokens.numeric)
             setIfMissing(values, key, generatedNumberForKey(key, options, random, numericConstraints.ranges.get(key)));
         for (const [elementName, { minimum, maximum }] of progressRanges) {

package/dist/hoi4_agent_tools/gui/source-graph.js

@@ -2,6 +2,7 @@ import path from 'node:path';
 import { compareCodeUnits, deterministicId } from '../core/canonical.js';
 import { DiagnosticCollector } from '../core/diagnostic-collector.js';
 import { sortDiagnostics } from '../core/diagnostics.js';
+import { SymbolIndex } from '../core/index.js';
 import { ServiceError } from '../core/result.js';
 import { GUI_GRAPH_MAX_EDGES, GUI_GRAPH_MAX_ELEMENTS, GUI_GRAPH_MAX_NODES } from './limits.js';
 import { assignments, childBlocks, firstScalar, locationFor, nodeLocation, parseClausewitz, parseLocalisation, } from '../core/source/index.js';
@@ -1306,7 +1307,8 @@ function referenceLabel(edge) {
         return String(value);
     return value === undefined ? edge.to : JSON.stringify(value);
 }
-export function buildGuiSourceGraph(files, sharedIndex, additionalLocalisationKeys = []) {
+export function buildGuiSourceGraph(files, providedIndex, additionalLocalisationKeys = [], limits = {}) {
+    const sharedIndex = providedIndex ?? new SymbolIndex();
     const activeFiles = files.filter(({ shadowedBy }) => shadowedBy === undefined);
     const nodes = [];
     const edges = [];
@@ -1323,25 +1325,6 @@ export function buildGuiSourceGraph(files, sharedIndex, additionalLocalisationKe
         category: 'layout',
         message: 'GUI source graph diagnostics exceeded the fixed global result ceiling',
     });
-    diagnostics.pushMany(sharedIndex.diagnostics);
-    if (!sharedIndex.complete) {
-        diagnostics.push({
-            code: 'GUI_INVENTORY_PARTIAL',
-            severity: 'warning',
-            category: 'reference',
-            message: sharedIndex.skippedSourceCount === 0
-                ? 'The GUI inventory is incomplete because the shared index reached a fixed record limit'
-                : `The GUI inventory skipped ${sharedIndex.skippedSourceCount} over-limit source${sharedIndex.skippedSourceCount === 1 ? '' : 's'}`,
-            details: {
-                skippedSourceCount: sharedIndex.skippedSourceCount,
-                retainedSkippedSources: sharedIndex.skippedSources.length,
-                skippedSources: sharedIndex.skippedSources.slice(0, 10).map(({ path, reasonCodes }) => ({
-                    path,
-                    reasonCodes,
-                })),
-            },
-        });
-    }
     const sourceHashes = {};
     const textureNodes = new Map();
     const fontAssetNodes = new Map();
@@ -1423,13 +1406,20 @@ export function buildGuiSourceGraph(files, sharedIndex, additionalLocalisationKe
         if (kind === undefined || fileNodeId === undefined) {
             if (/\.(?:txt|gui|gfx)$/u.test(normalized)) {
                 const document = parseClausewitz(file.bytes, file.displayPath);
+                if (providedIndex === undefined &&
+                    !sharedIndex.recordSourceCoverage(file, document.diagnostics))
+                    continue;
                 if (file.rootKind === 'mod' || file.rootKind === 'fixture')
                     diagnostics.pushMany(document.diagnostics);
-                indexDecisionEntries(document, file, nodes, pendingDecisionEdges);
+                if (/^common\/decision(?:s|_categories)\//u.test(normalized))
+                    indexDecisionEntries(document, file, nodes, pendingDecisionEdges);
             }
             continue;
         }
         const document = parseClausewitz(file.bytes, file.displayPath);
+        if (providedIndex === undefined &&
+            !sharedIndex.recordSourceCoverage(file, document.diagnostics))
+            continue;
         if (file.rootKind === 'mod' || file.rootKind === 'fixture')
             diagnostics.pushMany(document.diagnostics);
         if (kind === 'gui_file')
@@ -1451,14 +1441,22 @@ export function buildGuiSourceGraph(files, sharedIndex, additionalLocalisationKe
     const referencedLocalisationKeys = referencedGuiLocalisationKeys(elements, scriptedLocalisation);
     for (const key of additionalLocalisationKeys)
         referencedLocalisationKeys.add(key);
+    const maximumCandidates = Math.min(GUI_GRAPH_MAX_NODES, limits.maximumLocalisationCandidates ?? GUI_GRAPH_MAX_NODES);
+    if (!Number.isSafeInteger(maximumCandidates) || maximumCandidates < 1)
+        throw new ServiceError('GUI_LOCALISATION_BUDGET_INVALID', 'Localisation candidate limit must be a positive safe integer');
+    let candidateCount = 0;
+    const localisationCandidates = new Map();
     for (const { file, fileNodeId } of localisationFiles.sort((left, right) => right.file.loadOrder - left.file.loadOrder ||
         compareCodeUnits(left.file.displayPath, right.file.displayPath))) {
         const document = parseLocalisation(file.bytes, file.displayPath);
+        if (providedIndex === undefined &&
+            !sharedIndex.recordSourceCoverage(file, document.diagnostics))
+            continue;
         if (file.rootKind === 'mod' || file.rootKind === 'fixture')
             diagnostics.pushMany(document.diagnostics);
         for (const entry of document.entries) {
-            if (!referencedLocalisationKeys.has(entry.key))
-                continue;
+            if (++candidateCount > maximumCandidates)
+                throw new ServiceError('GUI_LOCALISATION_BUDGET_BLOCKED', 'Localisation dependency inventory exceeds the fixed candidate ceiling', { maximumCandidates });
             const value = {
                 key: entry.key,
                 language: entry.language,
@@ -1466,21 +1464,55 @@ export function buildGuiSourceGraph(files, sharedIndex, additionalLocalisationKe
                 sourcePath: file.displayPath,
                 location: locationFor(file.displayPath, document.lineIndex, entry.start, entry.end),
             };
+            const candidates = localisationCandidates.get(entry.key) ?? [];
+            candidates.push({ value, fileNodeId });
+            localisationCandidates.set(entry.key, candidates);
+        }
+    }
+    const pendingKeys = [...referencedLocalisationKeys];
+    for (const key of pendingKeys) {
+        for (const { value, fileNodeId } of localisationCandidates.get(key) ?? []) {
             addDomainEntry(localisation, value, 'localisation');
             const id = deterministicId('gui_loc', value);
             addNode(nodes, {
                 id,
                 kind: 'localisation',
-                name: entry.key,
-                path: file.displayPath,
+                name: key,
+                path: value.sourcePath,
                 ...(value.location === undefined ? {} : { location: value.location }),
-                metadata: { language: entry.language, value: entry.value },
+                metadata: { language: value.language, value: value.value },
             });
             addEdge(edges, 'contains', fileNodeId, id, true, {}, value.location);
+            for (const match of value.value.matchAll(/\$([A-Za-z0-9_.-]+)(?:\|[^$]*)?\$/gu)) {
+                const dependency = match[1];
+                if (!referencedLocalisationKeys.has(dependency)) {
+                    referencedLocalisationKeys.add(dependency);
+                    pendingKeys.push(dependency);
+                }
+            }
         }
     }
     linkGraph(nodes, edges, elements, sprites, fonts, scriptedGuis, scriptedLocalisation, localisation, textureNodes, fontAssetNodes, pendingDecisionEdges);
     linkAnimationSources(nodes, edges, animationSources, sprites, textureNodes, animationFrameNodes);
+    diagnostics.pushMany(sharedIndex.diagnostics);
+    if (!sharedIndex.complete) {
+        diagnostics.push({
+            code: 'GUI_INVENTORY_PARTIAL',
+            severity: 'warning',
+            category: 'reference',
+            message: sharedIndex.skippedSourceCount === 0
+                ? 'The GUI inventory is incomplete because the shared index reached a fixed record limit'
+                : `The GUI inventory skipped ${sharedIndex.skippedSourceCount} over-limit source${sharedIndex.skippedSourceCount === 1 ? '' : 's'}`,
+            details: {
+                skippedSourceCount: sharedIndex.skippedSourceCount,
+                retainedSkippedSources: sharedIndex.skippedSources.length,
+                skippedSources: sharedIndex.skippedSources.slice(0, 10).map(({ path, reasonCodes }) => ({
+                    path,
+                    reasonCodes,
+                })),
+            },
+        });
+    }
     markPartialReferenceEdges(edges, sharedIndex);
     diagnostics.pushMany(referenceDiagnostics(edges));
     if (nodes.length > GUI_GRAPH_MAX_NODES ||