hoi4-agent-tools 1.2.0 → 2.1.0

package/dist/hoi4_agent_tools/map/diagnostic-limit.js

@@ -1,18 +1,99 @@
 export const MAP_DIAGNOSTIC_LIMIT = 2_000;
-export function addMapDiagnostic(diagnostics, diagnostic) {
-    if (diagnostics.at(-1)?.code === 'MAP_DIAGNOSTICS_TRUNCATED')
+function isHardDiagnostic(diagnostic) {
+    return diagnostic.severity === 'error' || diagnostic.severity === 'blocker';
+}
+function isWorkspacePath(path) {
+    return path.startsWith('mod:') || path.startsWith('fixture:');
+}
+function isBaselineOnlyDiagnostic(diagnostic) {
+    if (diagnostic.location === undefined || isWorkspacePath(diagnostic.location.path))
+        return false;
+    return !(diagnostic.related ?? []).some(({ path }) => isWorkspacePath(path));
+}
+function addOmittedDiagnostic(details, diagnostic) {
+    details.omitted += 1;
+    details.omittedBySeverity[diagnostic.severity] =
+        (details.omittedBySeverity[diagnostic.severity] ?? 0) + 1;
+    details.omittedByCode[diagnostic.code] = (details.omittedByCode[diagnostic.code] ?? 0) + 1;
+}
+function truncationDiagnostic(omitted) {
+    const details = {
+        limit: MAP_DIAGNOSTIC_LIMIT,
+        retained: MAP_DIAGNOSTIC_LIMIT - 1,
+        omitted: 0,
+        omittedBySeverity: {},
+        omittedByCode: {},
+    };
+    for (const diagnostic of omitted)
+        addOmittedDiagnostic(details, diagnostic);
+    const hardOmitted = omitted.some(isHardDiagnostic);
+    return {
+        code: 'MAP_DIAGNOSTICS_TRUNCATED',
+        severity: hardOmitted ? 'blocker' : 'info',
+        category: 'map',
+        message: hardOmitted
+            ? 'Map diagnostic detail exceeded the result ceiling and omitted an error or blocker'
+            : 'Map diagnostic detail exceeded the result ceiling; deterministic samples and omission counts were retained',
+        details,
+    };
+}
+function existingTruncationDiagnostic(diagnostics) {
+    const marker = diagnostics.at(-1);
+    return marker?.code === 'MAP_DIAGNOSTICS_TRUNCATED'
+        ? marker
+        : undefined;
+}
+function addBoundedDiagnostic(diagnostics, diagnostic, includeBaseline) {
+    if (!includeBaseline && isBaselineOnlyDiagnostic(diagnostic))
+        return;
+    const marker = existingTruncationDiagnostic(diagnostics);
+    if (marker !== undefined) {
+        if (isHardDiagnostic(diagnostic)) {
+            const replaceIndex = diagnostics
+                .slice(0, -1)
+                .findLastIndex((retained) => !isHardDiagnostic(retained));
+            if (replaceIndex >= 0) {
+                const replaced = diagnostics[replaceIndex];
+                diagnostics[replaceIndex] = diagnostic;
+                addOmittedDiagnostic(marker.details, replaced);
+                return;
+            }
+            marker.severity = 'blocker';
+            marker.message =
+                'Map diagnostic detail exceeded the result ceiling and omitted an error or blocker';
+        }
+        addOmittedDiagnostic(marker.details, diagnostic);
         return;
+    }
     if (diagnostics.length < MAP_DIAGNOSTIC_LIMIT) {
         diagnostics.push(diagnostic);
         return;
     }
-    diagnostics[MAP_DIAGNOSTIC_LIMIT - 1] = {
-        code: 'MAP_DIAGNOSTICS_TRUNCATED',
-        severity: 'blocker',
-        category: 'map',
-        message: 'Map diagnostics exceeded the configured output limit',
-        details: { limit: MAP_DIAGNOSTIC_LIMIT, retained: MAP_DIAGNOSTIC_LIMIT - 1 },
-    };
+    const candidates = [...diagnostics, diagnostic];
+    const hard = candidates.filter(isHardDiagnostic);
+    const soft = candidates.filter((candidate) => !isHardDiagnostic(candidate));
+    const retained = hard.length >= MAP_DIAGNOSTIC_LIMIT - 1
+        ? hard.slice(0, MAP_DIAGNOSTIC_LIMIT - 1)
+        : [...hard, ...soft.slice(0, MAP_DIAGNOSTIC_LIMIT - 1 - hard.length)];
+    const retainedCounts = new Map();
+    for (const item of retained)
+        retainedCounts.set(item, (retainedCounts.get(item) ?? 0) + 1);
+    const omitted = candidates.filter((candidate) => {
+        const count = retainedCounts.get(candidate) ?? 0;
+        if (count === 0)
+            return true;
+        retainedCounts.set(candidate, count - 1);
+        return false;
+    });
+    diagnostics.splice(0, diagnostics.length, ...retained, truncationDiagnostic(omitted));
+}
+export function addMapDiagnostic(diagnostics, diagnostic) {
+    addBoundedDiagnostic(diagnostics, diagnostic, false);
+}
+/** Active topology validation must report failures in whichever source wins
+ * precedence, including inherited game and dependency files. */
+export function addActiveMapDiagnostic(diagnostics, diagnostic) {
+    addBoundedDiagnostic(diagnostics, diagnostic, true);
 }
 export function addMapDiagnostics(diagnostics, additions) {
     for (const diagnostic of additions)

package/dist/hoi4_agent_tools/map/model.js

@@ -24,11 +24,13 @@ const MAP_TEXT_FIELD_LIMIT = 10_000;
 const MAP_MODEL_MAX_SCRIPT_FILES = 5_000;
 const MAP_MODEL_MAX_SOURCE_TOKENS = 1_000_000;
 const MAP_MODEL_MAX_RECORDS = 500_000;
+const MAP_MODEL_MAX_LOCALISATION_RECORDS = 2_000_000;
 const MAP_MODEL_MAX_MEMBERSHIP_EDGES = 1_000_000;
 class MapModelBudget {
     #documents = new Set();
     #tokens = 0;
     #records = 0;
+    #localisationRecords = 0;
     #membershipEdges = 0;
     assertScriptFiles(count) {
         if (count > MAP_MODEL_MAX_SCRIPT_FILES) {
@@ -50,6 +52,13 @@ class MapModelBudget {
             this.block('domain records', this.#records, MAP_MODEL_MAX_RECORDS);
         }
     }
+    addLocalisationRecords(count) {
+        this.#localisationRecords += count;
+        if (!Number.isSafeInteger(this.#localisationRecords) ||
+            this.#localisationRecords > MAP_MODEL_MAX_LOCALISATION_RECORDS) {
+            this.block('localisation records', this.#localisationRecords, MAP_MODEL_MAX_LOCALISATION_RECORDS);
+        }
+    }
     addMembershipEdges(count) {
         this.#membershipEdges += count;
         if (!Number.isSafeInteger(this.#membershipEdges) ||
@@ -869,7 +878,9 @@ export class MapWorkspaceIndex {
         const modelBudget = new MapModelBudget();
         modelBudget.assertScriptFiles(this.sourceFiles.filter((file) => inConfiguredRoot(file.relativePath, this.sourceRoots.states) ||
             this.sourceRoots.map.some((root) => normalizedPath(file.relativePath).startsWith(`${root}/strategicregions/`)) ||
-            normalizedPath(file.relativePath).endsWith('.asset')).length);
+            ((file.rootKind === 'mod' || file.rootKind === 'fixture') &&
+                normalizedPath(file.relativePath).endsWith('.asset') &&
+                file.bytes.includes('locator'))).length);
         this.defaultMapFile = fileInRoots(this.activeFiles, this.sourceRoots.map, 'default.map');
         const definitionsName = defaultMapSelectorValue(this.defaultMapFile, 'definitions', 'definition.csv');
         const provincesName = defaultMapSelectorValue(this.defaultMapFile, 'provinces', 'provinces.bmp');
@@ -1031,7 +1042,9 @@ export class MapWorkspaceIndex {
             weatherFile === undefined ? [] : parseWeatherPositions(weatherFile, this.diagnostics);
         modelBudget.addRecords(this.weatherPositions.length);
         this.entityLocators = this.activeFiles.all
-            .filter((file) => normalizedPath(file.relativePath).endsWith('.asset'))
+            .filter((file) => (file.rootKind === 'mod' || file.rootKind === 'fixture') &&
+            normalizedPath(file.relativePath).endsWith('.asset') &&
+            file.bytes.includes('locator'))
             .flatMap((file) => {
             const locators = parseEntityLocators(file, this.diagnostics);
             if (locators[0] !== undefined)
@@ -1042,8 +1055,13 @@ export class MapWorkspaceIndex {
         for (const file of this.activeFiles.all.filter((entry) => inConfiguredRoot(entry.relativePath, this.sourceRoots.localisation) &&
             normalizedPath(entry.relativePath).endsWith('.yml'))) {
             const document = parseLocalisation(file.bytes, file.displayPath);
-            addMapDiagnostics(this.diagnostics, document.diagnostics);
-            modelBudget.addRecords(document.entries.length);
+            if (file.rootKind === 'mod' || file.rootKind === 'fixture') {
+                addMapDiagnostics(this.diagnostics, document.diagnostics);
+            }
+            // Localisation is a supporting lookup table rather than connected map topology. Account for
+            // it separately so a normal full-game language database cannot exhaust the domain-record
+            // budget before provinces, states, regions, railways, and adjacencies are available.
+            modelBudget.addLocalisationRecords(document.entries.length);
             for (const entry of document.entries) {
                 this.localisationKeys.add(`${entry.language}:${entry.key}`);
                 const indexed = { file, document, entry };

package/dist/hoi4_agent_tools/map/service.js

@@ -4,6 +4,7 @@ import { ArtifactStore, boundedSourceHashEvidence, publicArtifactLink, } from '.
 import { canonicalJson, compareCodeUnits, hashCanonical, sha256Bytes } from '../core/canonical.js';
 import { sortDiagnostics } from '../core/diagnostics.js';
 import { CoreEngine } from '../core/engine.js';
+import { SymbolIndex } from '../core/index.js';
 import { RenderBudget } from '../core/render-budget.js';
 import { ServiceError } from '../core/result.js';
 import { WorkspaceScanner } from '../core/scanner.js';
@@ -386,7 +387,6 @@ function sourceTextPatterns(roots) {
             const normalized = normalizeSourceRoot(root);
             return [`${normalized}/english/**/*.{yml,yaml}`, `${normalized}/*.{yml,yaml}`];
         }),
-        '**/*.asset',
     ];
 }
 function provinceBitmapPatterns(defaultMaps, mapRoots) {
@@ -491,14 +491,15 @@ export class AgentNudger {
         const selectorSnapshot = await this.engine.scan(workspaceId, { patterns: defaultMapPatterns(sourceRoots) }, principal, signal);
         const bitmapPatterns = provinceBitmapPatterns(selectorSnapshot.files, sourceRoots.map);
         const contentSnapshot = await this.engine.scan(workspaceId, { patterns: [...sourceTextPatterns(sourceRoots), ...bitmapPatterns] }, principal, signal);
+        const locatorSnapshot = await this.engine.scan(workspaceId, { patterns: ['**/*.asset'], rootKinds: ['mod', 'fixture'] }, principal, signal);
         signal?.throwIfAborted();
-        const files = contentSnapshot.files;
+        const files = [...contentSnapshot.files, ...locatorSnapshot.files].sort((left, right) => left.loadOrder - right.loadOrder || compareCodeUnits(left.displayPath, right.displayPath));
         const revision = hashCanonical(files.map(({ displayPath, loadOrder, sha256 }) => ({ displayPath, loadOrder, sha256 })));
         return {
             workspaceId,
             revision,
             files,
-            index: MapWorkspaceIndex.build(files, sourceRoots, contentSnapshot.index),
+            index: MapWorkspaceIndex.build(files, sourceRoots, SymbolIndex.build(files)),
         };
     }
     async validate(workspaceId, principal, signal) {

package/dist/hoi4_agent_tools/map/validation.js

@@ -1,7 +1,7 @@
 import { setImmediate as yieldToEventLoop } from 'node:timers/promises';
 import { sortDiagnostics } from '../core/diagnostics.js';
 import { assertRenderDimensions } from '../core/render-budget.js';
-import { addMapDiagnostic as addBoundedMapDiagnostic } from './diagnostic-limit.js';
+import { addActiveMapDiagnostic, addMapDiagnostic } from './diagnostic-limit.js';
 import { rgbKey } from './bmp.js';
 import { MAP_PROVINCE_ENGINE_MAX_PIXELS } from './model.js';
 const MAP_DIAGNOSTIC_DETAIL_SAMPLE_LIMIT = 100;
@@ -53,7 +53,8 @@ function definitionLocation(definition) {
     return requiredLineLocation(definition.document, definition.line);
 }
 function addDiagnostic(diagnostics, options, diagnostic) {
-    addBoundedMapDiagnostic(diagnostics, {
+    const add = options.includeBaselineDiagnostics === true ? addActiveMapDiagnostic : addMapDiagnostic;
+    add(diagnostics, {
         ...diagnostic,
         ...(diagnostic.operationId !== undefined || options.operationId === undefined
             ? {}

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

@@ -1,12 +1,11 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { PACKAGE_NAME, PACKAGE_VERSION } from '../../version.js';
-import { registerModsTool } from '../tools/mods.js';
 import { registerFocusTools } from '../tools/focus.js';
 import { registerGuiTools } from '../tools/gui.js';
 import { registerMapTools } from '../tools/map.js';
 import { registerEventTools } from '../tools/event.js';
 import { registerMcpResources } from '../resources/register.js';
-export const SERVER_INSTRUCTIONS = 'Use hoi4.mods to select a workspace. Use hoi4.event_inspect for scan, roots, trace, explain_path, state_flow, lint, and impact; hoi4.event_render and hoi4.event_compare return linked evidence. JSON resources are authoritative. Event tools are read-only. Only focus, GUI, and map rewrite tools edit configured mods.';
+export const SERVER_INSTRUCTIONS = 'Use hoi4.focus_inspect and hoi4.focus_render for fast structural work; hoi4.focus_raster adds decoded icons and PNG output. Use hoi4.event_inspect to analyze event chains. Event tools are read-only. Focus, GUI, and map rewrite tools edit the current mod. Large evidence is returned through linked resources.';
 export function createMcpServer(engine, context = {}) {
     const server = new McpServer({
         name: PACKAGE_NAME,
@@ -16,7 +15,6 @@ export function createMcpServer(engine, context = {}) {
         capabilities: { logging: {} },
         instructions: SERVER_INSTRUCTIONS,
     });
-    registerModsTool(server, engine, context);
     registerFocusTools(server, engine, context);
     registerGuiTools(server, engine, context);
     registerMapTools(server, engine, context);

package/dist/hoi4_agent_tools/mcp/server/output-schemas.js

@@ -16,7 +16,7 @@ export const renderHashesSchema = z
     .object({
     html: sha256Schema,
     svg: sha256Schema,
-    png: sha256Schema,
+    png: sha256Schema.optional(),
     json: sha256Schema,
 })
     .strict();

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

@@ -306,11 +306,11 @@ export function registerEventTools(server, engine, context) {
         outputSchema: eventInspectOutputSchema,
         annotations: readOnlyEventTool,
     }, async (input, extra) => {
-        const { workspaceId } = input;
+        const workspaceId = engine.resolver.resolveWorkspaceId(input.workspaceId, context.principal);
         try {
             const progress = progressReporter(extra);
             await progress.report(0, 3, 'Analyzing event chain');
-            const inspected = await viewer.inspect(inspectRequest(input, context, progress.signal));
+            const inspected = await viewer.inspect(inspectRequest({ ...input, workspaceId }, context, progress.signal));
             await progress.report(2, 3, 'Linking complete event analysis');
             const result = emptyServiceResult(workspaceId, {
                 mode: inspected.mode,
@@ -344,11 +344,11 @@ export function registerEventTools(server, engine, context) {
         outputSchema: eventRenderOutputSchema,
         annotations: readOnlyEventTool,
     }, async (input, extra) => {
-        const { workspaceId } = input;
+        const workspaceId = engine.resolver.resolveWorkspaceId(input.workspaceId, context.principal);
         try {
             const progress = progressReporter(extra);
             await progress.report(0, 3, 'Rendering event-chain view');
-            const rendered = await viewer.renderAndStore(renderRequest(input, context, progress.signal));
+            const rendered = await viewer.renderAndStore(renderRequest({ ...input, workspaceId }, context, progress.signal));
             await progress.report(2, 3, 'Linking complete event renders');
             const result = emptyServiceResult(workspaceId, {
                 view: rendered.render.view,
@@ -389,11 +389,11 @@ export function registerEventTools(server, engine, context) {
         outputSchema: eventCompareOutputSchema,
         annotations: readOnlyEventTool,
     }, async (input, extra) => {
-        const { workspaceId } = input;
+        const workspaceId = engine.resolver.resolveWorkspaceId(input.workspaceId, context.principal);
         try {
             const progress = progressReporter(extra);
             await progress.report(0, 3, 'Comparing event-chain graphs');
-            const compared = await viewer.compareAndStore(compareRequest(input, context, progress.signal));
+            const compared = await viewer.compareAndStore(compareRequest({ ...input, workspaceId }, context, progress.signal));
             await progress.report(2, 3, 'Linking complete event comparison');
             const { comparison } = compared;
             const result = emptyServiceResult(workspaceId, {