hoi4-agent-tools 4.0.1 → 4.0.4

package/dist/hoi4_agent_tools/gui/studio.js

@@ -9,6 +9,7 @@ import { CoreEngine } from '../core/engine.js';
 import { ClausewitzEvaluationDefinitions } from '../core/clausewitz-evaluation.js';
 import { assertRenderDimensions, RenderBudget, RENDER_MAX_PIXELS } from '../core/render-budget.js';
 import { escapeFileGlob } from '../core/file-glob.js';
+import { renderStage } from '../core/render-progress.js';
 import { ServiceError } from '../core/result.js';
 import { WorkspaceScanner } from '../core/scanner.js';
 import { applyReplacements, decodeSource, encodeSource, parseClausewitz, parseLocalisation, SOURCE_MAX_BYTES, sourcePartialLimitDiagnostics, } from '../core/source/index.js';
@@ -22,7 +23,7 @@ import { projectGuiGraphForArtifact } from './inspection-artifact.js';
 import { buildGuiScene } from './layout.js';
 import { GUI_VALIDATION_MAX_DIAGNOSTICS } from './limits.js';
 import { compareGuiImages, galleryDimensions, renderGallerySvg, renderGuiScene, } from './renderer.js';
-import { generateGuiPreviewScenarios, resolveScenarioScriptedLocalisation, } from './scenario-generator.js';
+import { generatedCountryTags, generateGuiPreviewScenarios, resolveScenarioScriptedLocalisation, } from './scenario-generator.js';
 import { parseGeneratedScenarioOptions, parsePreviewScenario } from './scenario.js';
 import { buildGuiSourceGraph } from './source-graph.js';
 import { assertGuiSourcePatchesSafe } from './source-patch.js';
@@ -242,13 +243,17 @@ function referenceVariants(value) {
     return candidates;
 }
 const FALLBACK_NAMES_PER_PATTERN = 100;
-function basenameFallbackPatterns(exactPaths, exactFiles) {
+function basenameFallbackPatterns(exactPaths, exactFiles, assetRoots = ['gfx', 'interface', 'fonts']) {
     const resolved = new Set(exactFiles
         .filter(({ shadowedBy }) => shadowedBy === undefined)
         .map(({ relativePath }) => relativePath.replaceAll('\\', '/').toLowerCase()));
+    const stem = (value) => value.toLowerCase().replace(/\.(?:png|bmp|tga|dds|svg|fnt|ttf|otf|woff2?)$/u, '');
+    const resolvedStems = new Set([...resolved].map(stem));
     const names = [
         ...new Set(exactPaths
-            .filter((candidate) => !/[*?[\]{}!]/u.test(candidate) && !resolved.has(candidate.toLowerCase()))
+            .filter((candidate) => !/[*?[\]{}!]/u.test(candidate) &&
+            !resolved.has(candidate.toLowerCase()) &&
+            !resolvedStems.has(stem(candidate)))
             .map((candidate) => path.posix.basename(candidate))),
     ].sort((left, right) => compareCodeUnits(left, right));
     // One brace group searches many names in a single bounded wildcard pattern, so a window
@@ -261,7 +266,9 @@ function basenameFallbackPatterns(exactPaths, exactFiles) {
         const chunk = grouped.slice(start, start + FALLBACK_NAMES_PER_PATTERN).map(escapeFileGlob);
         patterns.push(chunk.length === 1 ? `**/${chunk[0]}` : `**/{${chunk.join(',')}}`);
     }
-    return patterns.sort((left, right) => compareCodeUnits(left, right));
+    return [...new Set(assetRoots)]
+        .flatMap((root) => patterns.map((pattern) => `${escapeFileGlob(normalizeConfiguredRoot(root))}/${pattern}`))
+        .sort(compareCodeUnits);
 }
 function selectedElements(graph, windowName, additionalTemplateNames = []) {
     const byId = new Map(graph.elements.map((element) => [element.id, element]));
@@ -549,10 +556,14 @@ export function scenarioCountryFlagPatterns(scenarios) {
         for (const values of [
             scenario.values,
             scenario.scriptedGui,
+            scenario.country ?? {},
             ...Object.values(scenario.lists).flat(),
         ]) {
             for (const [key, value] of Object.entries(values)) {
-                if (key.endsWith('.countryTag') &&
+                if ((key.endsWith('.countryTag') ||
+                    key.endsWith('.tag') ||
+                    /(?:^|\.)GetFlag$/u.test(key) ||
+                    ['countryTag', 'GetTag', 'tag'].includes(key)) &&
                     typeof value === 'string' &&
                     /^[A-Za-z0-9_]{2,64}$/u.test(value))
                     tags.add(value.toUpperCase());
@@ -573,8 +584,14 @@ export function scenarioCountryFlagPatterns(scenarios) {
 function scenarioCountryHistoryPatterns(scenarios) {
     return scenarios.some(scenarioNeedsCountryHistory) ? ['history/countries/*.txt'] : [];
 }
-function scenarioCountryAssetPatterns(scenarios) {
-    return [...scenarioCountryFlagPatterns(scenarios), ...scenarioCountryHistoryPatterns(scenarios)];
+function scenarioCountryAssetPatterns(scenarios, generated = false) {
+    const flags = generated
+        ? [
+            ...scenarios,
+            ...generatedCountryTags.map((tag) => parsePreviewScenario({ id: `generated-${tag}`, country: { tag } })),
+        ]
+        : scenarios;
+    return [...scenarioCountryFlagPatterns(flags), ...scenarioCountryHistoryPatterns(scenarios)];
 }
 function bmFontPagePatterns(files) {
     const references = files.flatMap((file) => {
@@ -972,13 +989,9 @@ export class ScriptedGuiStudio {
             return cached;
         }
         const retainedFiles = [...files];
-        // The previous graph of this scope still indexes every unchanged file.
-        const previous = [...this.#graphCache].find(([existing]) => existing.startsWith(`${scope}:`))?.[1].index;
-        const index = this.engine.indexFiles(retainedFiles, previous);
         const scanned = {
             files: retainedFiles,
-            graph: buildGuiSourceGraph(retainedFiles, index, additionalLocalisationKeys),
-            index,
+            graph: buildGuiSourceGraph(retainedFiles, undefined, additionalLocalisationKeys),
         };
         // One graph per scope: a preview builds layout, game-layout and definition graphs, and a
         // single shared slot made each repeat call rebuild all of them.
@@ -1003,24 +1016,33 @@ export class ScriptedGuiStudio {
         signal?.throwIfAborted();
         const workspace = this.resolver.get(workspaceId, principal);
         const [snapshot, localisationFiles] = await Promise.all([
-            this.engine.scan(workspaceId, { patterns: guiDefinitionPatterns(workspace) }, principal, signal),
+            this.scanner.scan(workspace, {
+                patterns: guiDefinitionPatterns(workspace),
+                ...(signal === undefined ? {} : { signal }),
+            }),
             this.scanner.scan(workspace, {
                 patterns: guiLocalisationPatterns(workspace, languages),
                 ...(signal === undefined ? {} : { signal }),
             }),
         ]);
         signal?.throwIfAborted();
-        const files = mergeScannedFiles(snapshot.files, localisationFiles);
+        const files = mergeScannedFiles(snapshot, localisationFiles);
         return this.graphForFiles(files, `workspace:${workspaceId}`);
     }
-    async scanWindow(workspaceId, windowName, principal, signal, languages = ['l_english'], additionalSpriteNames = [], additionalTemplateNames = [], additionalAssetPatterns = [], additionalLocalisationKeys = [], includeImmediateTooltip = false) {
+    async scanWindow(workspaceId, windowName, principal, signal, languages = ['l_english'], additionalSpriteNames = [], additionalTemplateNames = [], additionalAssetPatterns = [], additionalLocalisationKeys = [], includeImmediateTooltip = false, progress) {
+        const stage = (phase) => renderStage({
+            ...(signal === undefined ? {} : { signal }),
+            ...(progress === undefined ? {} : { progress }),
+        }, phase);
+        await stage('Scanning GUI layouts');
         const workspace = this.resolver.get(workspaceId, principal);
         const layoutPatterns = guiLayoutPatterns(workspace);
-        const overlayLayouts = await this.engine.scan(workspaceId, {
+        const overlayLayouts = await this.scanner.scan(workspace, {
             patterns: layoutPatterns,
             rootKinds: ['mod', 'dependency', 'fixture'],
-        }, principal, signal);
-        let layoutFiles = overlayLayouts.files;
+            ...(signal === undefined ? {} : { signal }),
+        });
+        let layoutFiles = overlayLayouts;
         let layoutGraph = this.graphForFiles(layoutFiles, `layout:${workspaceId}`).graph;
         const selectedLayoutElements = selectedElements(layoutGraph, windowName, additionalTemplateNames);
         const requiredNames = new Set([windowName, ...additionalTemplateNames]);
@@ -1028,25 +1050,38 @@ export class ScriptedGuiStudio {
             collectNamedAttributes(element.attributes, new Set(['verticalScrollbar', 'horizontalScrollbar', 'scrollbarType', 'scrollbartype']), requiredNames);
         const availableNames = new Set(layoutGraph.elements.map(({ name }) => name));
         if ([...requiredNames].some((name) => !availableNames.has(name))) {
-            const gameLayouts = await this.engine.scan(workspaceId, { patterns: layoutPatterns, rootKinds: ['game', 'dlc'] }, principal, signal);
-            const gameGraph = this.graphForFiles(gameLayouts.files, `game-layout:${workspaceId}`).graph;
+            const gameLayouts = await this.scanner.scan(workspace, {
+                patterns: layoutPatterns,
+                rootKinds: ['game', 'dlc'],
+                ...(signal === undefined ? {} : { signal }),
+            });
+            const gameGraph = this.graphForFiles(gameLayouts, `game-layout:${workspaceId}`).graph;
             const selectedPaths = new Set(selectedElements(gameGraph, windowName, [...requiredNames]).map(({ sourcePath }) => sourcePath));
-            layoutFiles = mergeScannedFiles(layoutFiles, gameLayouts.files.filter(({ displayPath }) => selectedPaths.has(displayPath)));
+            layoutFiles = mergeScannedFiles(layoutFiles, gameLayouts.filter(({ displayPath }) => selectedPaths.has(displayPath)));
             layoutGraph = this.graphForFiles(layoutFiles, `merged-layout:${workspaceId}`).graph;
         }
         if (!layoutGraph.elements.some(({ name }) => name === windowName))
             assertTargetWindowAvailable(layoutGraph, windowName);
+        await stage('Scanning GUI definitions and localisation');
         const [linkedDefinitions, localisation] = await Promise.all([
-            this.engine.scan(workspaceId, { patterns: guiLinkedDefinitionPatterns(workspace) }, principal, signal),
-            this.engine.scan(workspaceId, { patterns: guiLocalisationPatterns(workspace, languages) }, principal, signal),
+            this.scanner.scan(workspace, {
+                patterns: guiLinkedDefinitionPatterns(workspace),
+                ...(signal === undefined ? {} : { signal }),
+            }),
+            this.scanner.scan(workspace, {
+                patterns: guiLocalisationPatterns(workspace, languages),
+                ...(signal === undefined ? {} : { signal }),
+            }),
         ]);
-        const definitionFiles = mergeScannedFiles(layoutFiles, linkedDefinitions.files, localisation.files);
+        const definitionFiles = mergeScannedFiles(layoutFiles, linkedDefinitions, localisation);
+        await stage('Building GUI source graph');
         const definitions = this.graphForFiles(definitionFiles, `definitions:${workspaceId}`, additionalLocalisationKeys);
         assertTargetWindowAvailable(definitions.graph, windowName);
         const referencedPatterns = [
-            ...referencedAssetPatternsForWindow(definitions.graph, windowName, additionalSpriteNames, languages, additionalTemplateNames, includeImmediateTooltip),
+            ...referencedAssetPatternsForWindow(definitions.graph, windowName, additionalSpriteNames, languages, additionalTemplateNames, includeImmediateTooltip).filter((pattern) => !pattern.startsWith('gfx/flags/')),
             ...additionalAssetPatterns,
         ];
+        await stage('Loading selected GUI assets');
         const exactReferenced = referencedPatterns.length === 0
             ? []
             : await this.scanner.scan(workspace, {
@@ -1054,7 +1089,11 @@ export class ScriptedGuiStudio {
                 ...(signal === undefined ? {} : { signal }),
             });
         signal?.throwIfAborted();
-        const fallbackPatterns = basenameFallbackPatterns(referencedPatterns, exactReferenced);
+        const fallbackPatterns = basenameFallbackPatterns(referencedPatterns, exactReferenced, [
+            ...workspace.registration.roots.gfx,
+            ...workspace.registration.roots.interface,
+            'fonts',
+        ]);
         const fallbackReferenced = fallbackPatterns.length === 0
             ? []
             : await this.scanner.scan(workspace, {
@@ -1070,7 +1109,11 @@ export class ScriptedGuiStudio {
                 ...(signal === undefined ? {} : { signal }),
             });
         signal?.throwIfAborted();
-        const fontPageFallbackPatterns = basenameFallbackPatterns(fontPagePatterns, exactFontPages);
+        const fontPageFallbackPatterns = basenameFallbackPatterns(fontPagePatterns, exactFontPages, [
+            ...workspace.registration.roots.gfx,
+            ...workspace.registration.roots.interface,
+            'fonts',
+        ]);
         const fallbackFontPages = fontPageFallbackPatterns.length === 0
             ? []
             : await this.scanner.scan(workspace, {
@@ -1079,7 +1122,26 @@ export class ScriptedGuiStudio {
             });
         const fontPages = mergeScannedFiles(exactFontPages, fallbackFontPages);
         signal?.throwIfAborted();
-        const files = mergeScannedFiles(definitions.files, referenced, fontPages);
+        const windowElements = selectedElements(definitions.graph, windowName, additionalTemplateNames);
+        const selectedPaths = new Set(windowElements.map(({ sourcePath }) => sourcePath));
+        const namedSprites = new Set(additionalSpriteNames);
+        const namedFonts = new Set();
+        for (const element of windowElements) {
+            collectNamedAttributes(element.attributes, new Set(['spriteType', 'quadTextureSprite']), namedSprites);
+            collectNamedAttributes(element.attributes, new Set(['font', 'buttonFont']), namedFonts);
+        }
+        const assetPaths = new Set(referencedPatterns.map((value) => value.toLowerCase()));
+        for (const sprite of definitions.graph.sprites)
+            if (namedSprites.has(sprite.name) ||
+                [sprite.texturePath, sprite.texturePath2, sprite.effectFile].some((value) => value !== undefined &&
+                    referenceVariants(value).some((variant) => assetPaths.has(variant.toLowerCase()))))
+                selectedPaths.add(sprite.sourcePath);
+        for (const font of definitions.graph.fonts)
+            if (namedFonts.has(font.name) ||
+                font.assetPaths.some((value) => referenceVariants(value).some((variant) => assetPaths.has(variant.toLowerCase()))))
+                selectedPaths.add(font.sourcePath);
+        const files = mergeScannedFiles(definitions.files.filter((file) => !/\.(?:gui|gfx)$/iu.test(file.relativePath) || selectedPaths.has(file.displayPath)), referenced, fontPages);
+        await stage('Resolving selected GUI assets');
         return this.graphForFiles(files, `window:${workspaceId}:${windowName}`, additionalLocalisationKeys);
     }
     async lint(input) {
@@ -1089,7 +1151,7 @@ export class ScriptedGuiStudio {
         const generatedOptions = input.generatedScenarios === undefined
             ? undefined
             : parseGeneratedScenarioOptions(input.generatedScenarios);
-        const scanned = await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [placeholderScenario.language, ...explicitRelatedScenarios.map(({ language }) => language)], scenarioSpriteNames([placeholderScenario, ...explicitRelatedScenarios], generatedOptions?.textSamples), scenarioTemplateNames([placeholderScenario, ...explicitRelatedScenarios]), scenarioCountryAssetPatterns([placeholderScenario, ...explicitRelatedScenarios]), scenarioLocalisationKeys([placeholderScenario, ...explicitRelatedScenarios]), [placeholderScenario, ...explicitRelatedScenarios].some(({ tooltip }) => tooltip !== undefined));
+        const scanned = await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [placeholderScenario.language, ...explicitRelatedScenarios.map(({ language }) => language)], scenarioSpriteNames([placeholderScenario, ...explicitRelatedScenarios], generatedOptions?.textSamples), scenarioTemplateNames([placeholderScenario, ...explicitRelatedScenarios]), scenarioCountryAssetPatterns([placeholderScenario, ...explicitRelatedScenarios], generatedOptions?.enabled === true), scenarioLocalisationKeys([placeholderScenario, ...explicitRelatedScenarios]), [placeholderScenario, ...explicitRelatedScenarios].some(({ tooltip }) => tooltip !== undefined), input.progress);
         let builtDefinitions;
         const evaluationDefinitions = () => (builtDefinitions ??= ClausewitzEvaluationDefinitions.build(scanned));
         const resolveLocalisation = (target) => resolveScenarioScriptedLocalisation(scanned.graph, input.windowName, target, evaluationDefinitions);
@@ -1108,6 +1170,7 @@ export class ScriptedGuiStudio {
         assertUniqueScenarioIds([scenario, ...relatedScenarios]);
         const budget = new RenderBudget();
         const catalog = new GuiAssetCatalog(scanned.graph, scanned.files, budget, scenario.language);
+        await renderStage(input, 'Laying out GUI and decoding visible assets');
         const scene = await buildGuiScene(scanned.graph, scanned.files, input.windowName, scenario, catalog);
         const relatedScenes = [];
         for (const related of relatedScenarios) {
@@ -1179,7 +1242,7 @@ export class ScriptedGuiStudio {
             placeholderScenario,
             ...(requestedBaselineScenario === undefined ? [] : [requestedBaselineScenario]),
             ...explicitRelatedScenarios,
-        ]), scenarioLocalisationKeys([
+        ], generatedOptions?.enabled === true), scenarioLocalisationKeys([
             placeholderScenario,
             ...(requestedBaselineScenario === undefined ? [] : [requestedBaselineScenario]),
             ...explicitRelatedScenarios,
@@ -1187,7 +1250,7 @@ export class ScriptedGuiStudio {
             placeholderScenario,
             ...(requestedBaselineScenario === undefined ? [] : [requestedBaselineScenario]),
             ...explicitRelatedScenarios,
-        ].some(({ tooltip }) => tooltip !== undefined));
+        ].some(({ tooltip }) => tooltip !== undefined), input.progress);
         let builtDefinitions;
         const evaluationDefinitions = () => (builtDefinitions ??= ClausewitzEvaluationDefinitions.build(scanned));
         const resolveLocalisation = (target) => resolveScenarioScriptedLocalisation(scanned.graph, input.windowName, target, evaluationDefinitions);
@@ -1207,7 +1270,9 @@ export class ScriptedGuiStudio {
         const baselineScenario = requestedBaselineScenario ??
             parsePreviewScenario({ ...scenario, id: `${scenario.id}-comparison`, state: 'normal' });
         const catalog = new GuiAssetCatalog(scanned.graph, scanned.files, budget, scenario.language);
+        await renderStage(input, 'Laying out GUI and decoding visible assets');
         const scene = await buildGuiScene(scanned.graph, scanned.files, input.windowName, scenario, catalog);
+        await renderStage(input, 'Rasterizing GUI views');
         const render = await renderGuiScene(scene, undefined, input.signal, budget);
         const fullRenderCache = new Map([
             [visualSceneKey(scene), fullImage(render)],
@@ -1319,6 +1384,7 @@ export class ScriptedGuiStudio {
         validation.diagnostics.push(...stateValidation.diagnostics, ...resolutionValidation.diagnostics);
         validation.checks.push(...stateValidation.checks, ...resolutionValidation.checks);
         const completeValidation = withGraphDiagnostics(validationGraph, validation);
+        await renderStage(input, 'Writing GUI galleries and evidence');
         const scenarioGallerySvg = renderGallerySvg(`${input.windowName} scripted scenario matrix`, scenarioItems);
         const stateGallerySvg = renderGallerySvg(`${input.windowName} state matrix`, stateItems);
         const resolutionGallerySvg = renderGallerySvg(`${input.windowName} resolution and UI-scale matrix`, resolutionItems);

package/dist/hoi4_agent_tools/gui/tool-operations.js

@@ -120,11 +120,14 @@ export async function inspectGui(engine, studio, input, context) {
             const linted = await studio.lint({
                 workspaceId: context.workspaceId,
                 windowName: input.windowName,
+                progress: (phase) => context.progress(1, 3, phase),
                 scenario: input.scenario,
                 ...(input.relatedScenarios === undefined
                     ? {}
                     : { relatedScenarios: input.relatedScenarios }),
-                generatedScenarios: input.generatedScenarios ?? {},
+                ...(input.generatedScenarios === undefined
+                    ? {}
+                    : { generatedScenarios: input.generatedScenarios }),
                 ...(context.principal === undefined ? {} : { principal: context.principal }),
                 ...(context.signal === undefined ? {} : { signal: context.signal }),
             });
@@ -217,6 +220,7 @@ export async function inspectGui(engine, studio, input, context) {
 export async function renderGui(studio, input, context) {
     await context.progress(0, 4, 'Building GUI source graph');
     const rendered = await studio.renderAndStore({
+        progress: (phase) => context.progress(1, 4, phase),
         workspaceId: context.workspaceId,
         windowName: input.windowName,
         scenario: input.scenario,
@@ -231,7 +235,9 @@ export async function renderGui(studio, input, context) {
                 })),
             }),
         ...(input.relatedScenarios === undefined ? {} : { relatedScenarios: input.relatedScenarios }),
-        generatedScenarios: input.generatedScenarios ?? {},
+        ...(input.generatedScenarios === undefined
+            ? {}
+            : { generatedScenarios: input.generatedScenarios }),
         ...(input.comparisonScenario === undefined
             ? {}
             : { comparisonScenario: input.comparisonScenario }),

package/dist/hoi4_agent_tools/mcp/server/create-modern-operations.js

@@ -17,7 +17,7 @@ import { referenceTools } from '../tools/reference.js';
 import { isReferenceTool, ReferenceToolService } from '../../reference/operations.js';
 import { ModernTaskAdapter, TASKS_EXTENSION } from './modern-tasks.js';
 import { SERVER_INSTRUCTIONS } from './instructions.js';
-import { modernProgressReporter, withProgressHeartbeat } from './progress.js';
+import { jobProgressReporter, modernProgressReporter, withProgressHeartbeat } from './progress.js';
 import { taskToolCatalog } from './task-tool-catalog.js';
 const rootsResponseSchema = z
     .object({
@@ -187,6 +187,7 @@ export function createModernOperationServer(engine, context = {}, tasks = new Op
             const progress = modernProgressReporter(extra);
             const result = await withProgressHeartbeat(async () => {
                 const completed = await adapter.call({ name: definition.name, arguments: arguments_ }, capabilities, operationContext, {
+                    progress: jobProgressReporter(progress),
                     requestId: extra.mcpReq.id,
                     signal: extra.mcpReq.signal,
                     ...(extra.sessionId === undefined ? {} : { sessionId: extra.sessionId }),

package/dist/hoi4_agent_tools/mcp/server/job-task-store.js

@@ -2,7 +2,7 @@ import { CallToolResultSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { jobTaskTiming } from '../../core/job-store.js';
 import { OperationTaskService, operationTaskCallSchema, operationTaskId, operationTaskMessage, operationTaskStatus, } from '../../core/operation-tasks.js';
 import { ServiceError } from '../../core/result.js';
-import { currentTaskRequestSignal } from './task-request-context.js';
+import { currentTaskRequestSignal, currentTaskRequestProgress } from './task-request-context.js';
 function legacyTask(record) {
     if (record.request.protocolTask === undefined)
         throw new ServiceError('TASK_NOT_FOUND', 'The requested protocol task does not exist');
@@ -44,6 +44,8 @@ export class PersistentJobTaskStore {
     }
     async getTask(value, _sessionId) {
         const record = await this.tasks.get(value, this.context());
+        if (record?.progress !== undefined)
+            await currentTaskRequestProgress()?.(record.progress.completed, record.progress.total ?? 1, record.progress.message);
         return record === null ? null : legacyTask(record);
     }
     async storeTaskResult(value, status, result, _sessionId) {

package/dist/hoi4_agent_tools/mcp/server/modern-tasks.js

@@ -112,6 +112,8 @@ export class ModernTaskAdapter {
             options.signal?.throwIfAborted();
             await delay(100, undefined, { signal: options.signal });
             latest = await this.known(taskId, context);
+            if (latest.progress !== undefined)
+                await options.progress?.(latest.progress.completed, latest.progress.total ?? 1, latest.progress.message);
         }
         return modernToolResult(latest, await this.tasks.result(operationTaskId(record), context));
     }

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

@@ -101,3 +101,15 @@ export async function withProgressHeartbeat(operation, reporter, message, interv
         heartbeatOwners.delete(reporter);
     }
 }
+/** Reserve the outer request's final two steps for retrieval/completion while forwarding worker phases. */
+export function jobProgressReporter(reporter) {
+    let previous;
+    return async (completed, total, message) => {
+        const identity = JSON.stringify([completed, total, message]);
+        if (identity === previous)
+            return;
+        previous = identity;
+        await reporter.report(Math.min(1, completed / Math.max(1, total)), 3, message);
+        await reporter.pulse(message);
+    };
+}

package/dist/hoi4_agent_tools/mcp/server/request-lifecycle.js

@@ -5,7 +5,7 @@ import { referenceTools } from '../tools/reference.js';
 import { jobControlTools } from '../tools/job.js';
 import { invalidArgumentsResult } from './argument-errors.js';
 import { taskToolCatalog } from './task-tool-catalog.js';
-import { progressReporter, withProgressHeartbeat } from './progress.js';
+import { jobProgressReporter, progressReporter, withProgressHeartbeat } from './progress.js';
 import { withTaskRequestSignal } from './task-request-context.js';
 import { slimToolList } from './tool-listing.js';
 // Durable task compatibility and cancellation are control traffic. They must
@@ -42,7 +42,7 @@ export function installRequestLifecycle(server, engine) {
                 return handler(request, extra);
             if (taskCall.success && backgroundTools.has(taskCall.data.params.name)) {
                 return withProgressHeartbeat(async () => {
-                    const result = await withTaskRequestSignal(extra.signal, () => handler(request, extra));
+                    const result = await withTaskRequestSignal(extra.signal, () => handler(request, extra), jobProgressReporter(progress));
                     if (taskCall.data.params.task === undefined) {
                         await progress.report(2, 3, 'Retrieving persistent operation result');
                         await progress.report(3, 3, 'Persistent operation complete');

package/dist/hoi4_agent_tools/mcp/server/task-request-context.js

@@ -1,9 +1,12 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 const taskRequestContext = new AsyncLocalStorage();
 /** Bind transport cancellation to foreground-compatible task creation only. */
-export function withTaskRequestSignal(signal, action) {
-    return taskRequestContext.run({ signal }, action);
+export function withTaskRequestSignal(signal, action, progress) {
+    return taskRequestContext.run({ signal, ...(progress === undefined ? {} : { progress }) }, action);
 }
 export function currentTaskRequestSignal() {
     return taskRequestContext.getStore()?.signal;
 }
+export function currentTaskRequestProgress() {
+    return taskRequestContext.getStore()?.progress;
+}

package/dist/hoi4_agent_tools/technology/job-operations.js

@@ -22,6 +22,7 @@ export function registerTechnologyJobs(operations, engine) {
                     workspaceId: context.workspaceId,
                     ...(context.principal === undefined ? {} : { principal: context.principal }),
                     signal: context.signal,
+                    progress: (phase) => context.progress({ completed: 1, total: 3, message: phase }),
                 });
                 await context.progress({
                     completed: 3,

package/dist/hoi4_agent_tools/technology/service.js

@@ -4,6 +4,7 @@ import { technologyHelperInventory } from './helper-expansion.js';
 import { clearSemanticDependencies } from '../core/semantic-dependencies.js';
 import { canonicalJson, compareCodeUnits, hashCanonical, sha256Bytes } from '../core/canonical.js';
 import { boundedSourceHashEvidence, } from '../core/artifacts.js';
+import { renderStage } from '../core/render-progress.js';
 import { RenderBudget } from '../core/render-budget.js';
 import { ServiceError } from '../core/result.js';
 import { SOURCE_MAX_BYTES } from '../core/source/index.js';
@@ -96,43 +97,17 @@ function technologyScanPatterns(workspace) {
         ...under(roots.localisation, '*.{yml,yaml}'),
     ].sort(compareCodeUnits);
 }
-function recomputeTechnologyShadowing(files) {
-    const groups = new Map();
-    for (const file of files) {
-        delete file.shadowedBy;
-        const key = file.relativePath.replaceAll('\\', '/').toLowerCase();
-        const group = groups.get(key) ?? [];
-        group.push(file);
-        groups.set(key, group);
-    }
-    for (const group of groups.values()) {
-        group.sort((left, right) => right.loadOrder - left.loadOrder || compareCodeUnits(left.displayPath, right.displayPath));
-        const active = group[0];
-        for (const shadowed of group.slice(1))
-            shadowed.shadowedBy = active.displayPath;
-    }
-}
-async function scanTechnologySources(engine, workspaceId, workspace, principal, signal) {
-    const patterns = technologyScanPatterns(workspace);
-    const scans = await Promise.all([
-        engine.scan(workspaceId, { patterns, rootKinds: ['mod', 'dependency', 'fixture'] }, principal, signal),
-        ...(workspace.roots.some(({ kind }) => kind === 'game')
-            ? [engine.scan(workspaceId, { patterns, rootKinds: ['game', 'dlc'] }, principal, signal)]
-            : []),
-    ]);
-    const files = scans.flatMap(({ files }) => files.map((file) => ({ ...file })));
-    recomputeTechnologyShadowing(files);
-    files.sort((left, right) => left.loadOrder - right.loadOrder || compareCodeUnits(left.displayPath, right.displayPath));
-    const index = engine.indexFiles(files);
+async function scanTechnologySources(engine, workspaceId, workspace, principal, signal, renderOnly = false) {
+    const patterns = technologyScanPatterns(workspace).filter((pattern) => !renderOnly ||
+        !/^(?:events|history|common\/(?:national_focus|decisions|scripted_effects|on_actions|ideas|characters))\//u.test(pattern));
+    const snapshot = await engine.scan(workspaceId, { patterns }, principal, signal);
     return {
-        workspaceId,
-        revision: hashCanonical(files.map(({ displayPath, loadOrder, sha256 }) => ({ displayPath, loadOrder, sha256 }))),
-        files,
-        index,
-        complete: scans.every(({ complete }) => complete) && index.complete,
-        skippedSourceCount: index.skippedSourceCount,
-        skippedSources: index.skippedSources,
-        diagnostics: [...scans.flatMap(({ diagnostics }) => diagnostics), ...index.diagnostics],
+        ...snapshot,
+        revision: hashCanonical(snapshot.files.map(({ displayPath, loadOrder, sha256 }) => ({
+            displayPath,
+            loadOrder,
+            sha256,
+        }))),
     };
 }
 function activeTechnologySprite(spriteName, spritePath, sprites) {
@@ -472,7 +447,7 @@ export class TechnologyTreeViewer {
         const workspace = this.engine.resolver.get(workspaceId, options.principal);
         const generation = this.engine.generation(workspaceId);
         const cached = this.#state.current.get(workspaceId);
-        const snapshot = await scanTechnologySources(this.engine, workspaceId, workspace, options.principal, options.signal);
+        const snapshot = await scanTechnologySources(this.engine, workspaceId, workspace, options.principal, options.signal, options.renderOnly);
         const analysisMode = workspace.roots.some(({ kind }) => kind === 'game') || snapshot.files.length > 1_000
             ? 'focused'
             : undefined;
@@ -526,6 +501,8 @@ export class TechnologyTreeViewer {
             ...(analysisMode === undefined ? {} : { analysisMode }),
             ...(options.signal === undefined ? {} : { signal: options.signal }),
         });
+        if (options.renderOnly === true)
+            graph.analysisBoundary.assumptions.push('Folder renders scan technology definitions, layouts, unlock targets and assets; inbound grants and references require technology inspection.');
         this.#state.current.set(workspaceId, { generation, snapshot, assetFiles, graph });
         rememberGraph(this.#state, graph);
         return graph;
@@ -650,7 +627,9 @@ export class TechnologyTreeViewer {
         };
     }
     async renderAndStore(input) {
+        await renderStage(input, 'Indexing technology view sources');
         const graph = await this.scan(input.workspaceId, {
+            renderOnly: input.view === 'folder',
             ...(input.refresh === undefined ? {} : { refresh: input.refresh }),
             ...(input.principal === undefined ? {} : { principal: input.principal }),
             ...(input.signal === undefined ? {} : { signal: input.signal }),
@@ -684,9 +663,11 @@ export class TechnologyTreeViewer {
                 maxNodes: 1_000,
             })),
         ]);
+        await renderStage(input, 'Decoding selected technology assets');
         const { dataUris: iconDataUris, dimensions: spriteDimensions } = await resolveTechnologyIconDataUris(cached, requestedIconSprites, budget, input.signal);
         renderOptions.iconDataUris = iconDataUris;
         renderOptions.spriteDimensions = spriteDimensions;
+        await renderStage(input, 'Laying out and rasterizing technology view');
         const render = await renderTechnologyGraph(graph, renderOptions);
         const focused = [];
         for (const folder of focusedFolders) {

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

package/docs/gui.md

@@ -11,6 +11,14 @@ Dashed amber regions are potential controls with unresolved visibility or enabli
 The scene retains the reason so the agent can supply the missing facts instead of guessing.
 These are source-model results, not proof of native click execution.
 
+## Render one supplied state
+
+For a focused render, use `states: []`, one `resolutions` entry matching `scenario.resolution`, and the flags, variables and list rows needed to open the window. Inspection and rendering preserve the supplied scenario; `generatedScenarios` is opt-in. A full state/resolution matrix still runs when those arrays are omitted.
+
+Progress reports scanning, graph construction, selected asset loading, layout and rasterization. Deadline errors name the last phase. Missing texture fallback searches configured graphics/interface roots and fonts, never documentation or unrelated workspace folders. Move assets under a configured asset root if they previously depended on a workspace-wide basename search.
+
+Nested `$KEY$` localisation references resolve across files. Scenario values can supply runtime tokens; cycles, more than 16 nested substitutions, and missing values remain unresolved. Animated sprites use `animationTimeSeconds` (and `visibleTimeSeconds` for play-on-show timing); each PNG is a deterministic frame at that time, not an animation.
+
 ## Preview immediate tooltip text
 
 An explicit tooltip request uses a visible element's `pdx_tooltip` localisation key. Supply `tooltip.target` with its inspected instance ID or a unique element name, plus viewport `x`, `y`, `width` and `padding` values.

package/docs/technology.md

@@ -127,3 +127,5 @@ The comparison render is produced unless `render` is `false`; `maxRenderNodes` r
 For an unfamiliar technology system, an agent can scan it, discover folders, trace or explain the relevant path, render only the needed views, edit Clausewitz source through its normal repository workflow, and compare the result. The same graph and revision back every query and artifact, so folder placement, dependency structure, unlock impact, and cross-file references stay aligned.
 
 This is static analysis. Exact runtime research time, AI choices, balance, arbitrary dynamic grants, and unsupported visibility behavior are not inferred. Dynamic expressions remain in the results with their confidence and blockers, and no destination is invented.
+
+Folder rendering scans technology definitions, GUI layouts, unlock targets, localisation and assets. It omits inbound event, decision, focus and history references; use `hoi4.tech_inspect` for grants, bonuses, impact and complete reference evidence. The render manifest records this source scope.

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "hoi4-agent-tools",
-  "version": "4.0.1",
+  "version": "4.0.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "hoi4-agent-tools",
-      "version": "4.0.1",
+      "version": "4.0.4",
       "license": "Apache-2.0",
       "dependencies": {
         "@fontsource-variable/roboto": "5.3.0",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hoi4-agent-tools",
   "mcpName": "io.github.klimPaskov/hoi4-agent-tools",
-  "version": "4.0.1",
+  "version": "4.0.4",
   "description": "Build HOI4 mods: focus trees, events, decisions, worlds, GUI previews, docs and AI balance.",
   "type": "module",
   "license": "Apache-2.0",

package/schemas/configuration.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.0.1/schemas/configuration.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.0.4/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/v4.0.1/schemas/continuous-focus-palette.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.0.4/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/v4.0.1/schemas/custom-weighted-pool.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.0.4/schemas/custom-weighted-pool.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

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

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