hoi4-agent-tools 1.1.0 → 2.0.0

package/dist/hoi4_agent_tools/focus/native-effects.js

@@ -5,7 +5,7 @@
  * Source: the official HOI4 1.19.2 effects documentation reviewed 2026-07-10.
  * Keep this list synchronized during compatibility reviews.
  */
-export const nativeFocusEffectKeys = new Set([
+export const nativeEffectKeys = new Set([
     'activate_advisor',
     'activate_decision',
     'activate_mission',
@@ -560,3 +560,5 @@ export const nativeFocusEffectKeys = new Set([
     'while_loop_effect',
     'white_peace',
 ]);
+/** Backward-compatible focus-domain name for the shared official effect catalog. */
+export const nativeFocusEffectKeys = nativeEffectKeys;

package/dist/hoi4_agent_tools/gui/layout.js

@@ -40,8 +40,55 @@ function scalarString(value) {
         return String(value);
     return undefined;
 }
+const defaultTextColour = '#f5f2e8';
+const hoi4TextColours = {
+    B: '#4aa3df',
+    C: '#55d6d6',
+    G: '#56b870',
+    H: '#e7b454',
+    L: '#9aa7b3',
+    M: '#d16bd4',
+    O: '#e58b3c',
+    R: '#e05a5a',
+    T: '#4bc6b9',
+    W: defaultTextColour,
+    Y: '#f1c75b',
+    b: '#4aa3df',
+    g: '#87939e',
+};
 function visibleHoiText(value) {
-    return value.replace(/\u00a7[A-Za-z0-9!]/gu, '').replace(/\u00a3[^\u00a3\s]+/gu, '\u25c6');
+    const characters = [];
+    const colours = [];
+    let colour;
+    let hasColourMarkup = false;
+    for (let index = 0; index < value.length; index += 1) {
+        const character = value[index] ?? '';
+        const next = value[index + 1];
+        if (character === '\u00a7' && next !== undefined && /^[A-Za-z0-9!]$/u.test(next)) {
+            hasColourMarkup = true;
+            colour = next === '!' ? undefined : hoi4TextColours[next];
+            index += 1;
+            continue;
+        }
+        if (character === '\u00a3') {
+            let cursor = index + 1;
+            while (cursor < value.length && !/[\s\u00a3]/u.test(value[cursor] ?? ''))
+                cursor += 1;
+            characters.push('\u25c6');
+            colours.push(colour);
+            index = cursor - 1;
+            continue;
+        }
+        if (character === '\\' && next === 'n') {
+            characters.push('\n');
+            colours.push(colour);
+            index += 1;
+            continue;
+        }
+        characters.push(character);
+        colours.push(colour);
+    }
+    return { text: characters.join(''), colours, hasColourMarkup };
 }
 function scalarNumber(value, reference) {
     if (typeof value === 'number')
@@ -167,13 +214,15 @@ function resolveTokenText(value, scenario, localisation, rowValues) {
         const key = match[1] ?? '';
         const replacement = rowValues?.[key] ?? scenario.variables[key] ?? scenario.scriptedGui[key];
         if (replacement === undefined) {
-            unresolved.push(`[?${key}]`);
-            return `[?${key}]`;
+            unresolved.push(match[0]);
+            return '[X]';
         }
         return String(replacement);
     }, 'GUI variable substitution');
     text = replaceTextBounded(text, /\[([A-Za-z0-9_.:-]+)\]/gu, (match) => {
         const key = match[1] ?? '';
+        if (key === 'X')
+            return match[0];
         const countryKey = key.replace(/^(?:ROOT|This)\./u, '');
         const replacement = rowValues?.[countryKey] ??
             scenario.country?.[countryKey] ??
@@ -181,16 +230,16 @@ function resolveTokenText(value, scenario, localisation, rowValues) {
             scenario.scriptedGui[key];
         if (replacement === undefined) {
             unresolved.push(match[0]);
-            return match[0];
+            return '[X]';
         }
         return String(replacement);
     }, 'GUI scope substitution');
     return { text, unresolved: [...new Set(unresolved)].sort(), missingLocalisation };
 }
-function wrapText(catalog, fontName, text, fontSize, maximumWidth, work) {
-    const paragraphs = text.replaceAll('\\n', '\n').split('\n');
+function wrapText(catalog, fontName, text, colours, fontSize, maximumWidth, work) {
     const lines = [];
     const widths = [];
+    const colourLines = [];
     const missingGlyphs = new Set();
     const retainMissingGlyphs = (values) => {
         for (const value of values) {
@@ -201,12 +250,44 @@ function wrapText(catalog, fontName, text, fontSize, maximumWidth, work) {
     };
     let lineHeight = fontSize * 1.2;
     let metricSource = 'approximation';
-    for (const paragraph of paragraphs) {
+    const commitLine = (words) => {
+        const characters = [];
+        const lineColours = [];
+        for (const [index, word] of words.entries()) {
+            if (index > 0) {
+                characters.push(' ');
+                lineColours.push(lineColours.at(-1) ?? word.colours[0]);
+            }
+            characters.push(word.text);
+            lineColours.push(...word.colours);
+        }
+        const committedText = characters.join('');
+        work.spendTextLayout('committed text line measurement');
+        const committed = catalog.measureText(fontName, committedText, fontSize);
+        lines.push(committedText);
+        widths.push(committed.width);
+        colourLines.push(lineColours);
+        retainMissingGlyphs(committed.missingGlyphs);
+        lineHeight = committed.lineHeight;
+        metricSource = committed.source;
+    };
+    let paragraphStart = 0;
+    for (let paragraphEnd = 0; paragraphEnd <= text.length; paragraphEnd += 1) {
+        if (paragraphEnd < text.length && text[paragraphEnd] !== '\n')
+            continue;
         work.spendTextLayout('text paragraph layout');
-        const words = paragraph.split(/\s+/u).filter((word) => word.length > 0);
+        const paragraph = text.slice(paragraphStart, paragraphEnd);
+        const paragraphColours = colours.slice(paragraphStart, paragraphEnd);
+        const words = [...paragraph.matchAll(/\S+/gu)].map((match) => {
+            const start = match.index;
+            const word = match[0];
+            return { text: word, colours: paragraphColours.slice(start, start + word.length) };
+        });
+        paragraphStart = paragraphEnd + 1;
         if (words.length === 0) {
             lines.push('');
             widths.push(0);
+            colourLines.push([]);
             continue;
         }
         let currentWords = [];
@@ -215,22 +296,17 @@ function wrapText(catalog, fontName, text, fontSize, maximumWidth, work) {
         let previousWordWidth = 0;
         for (const word of words) {
             work.spendTextLayout('text word measurement');
-            const measuredWord = catalog.measureText(fontName, word, fontSize);
+            const measuredWord = catalog.measureText(fontName, word.text, fontSize);
             retainMissingGlyphs(measuredWord.missingGlyphs);
             let candidateWidth = measuredWord.width;
             if (previousWord !== undefined) {
                 work.spendTextLayout('text word-boundary measurement');
-                const boundary = catalog.measureText(fontName, `${previousWord} ${word}`, fontSize);
+                const boundary = catalog.measureText(fontName, `${previousWord} ${word.text}`, fontSize);
                 retainMissingGlyphs(boundary.missingGlyphs);
                 candidateWidth = currentWidth + boundary.width - previousWordWidth;
             }
             if (maximumWidth > 0 && candidateWidth > maximumWidth && currentWords.length > 0) {
-                const committedText = currentWords.join(' ');
-                work.spendTextLayout('committed text line measurement');
-                const committed = catalog.measureText(fontName, committedText, fontSize);
-                lines.push(committedText);
-                widths.push(committed.width);
-                retainMissingGlyphs(committed.missingGlyphs);
+                commitLine(currentWords);
                 currentWords = [word];
                 currentWidth = measuredWord.width;
             }
@@ -238,26 +314,40 @@ function wrapText(catalog, fontName, text, fontSize, maximumWidth, work) {
                 currentWords.push(word);
                 currentWidth = candidateWidth;
             }
-            previousWord = word;
+            previousWord = word.text;
             previousWordWidth = measuredWord.width;
         }
-        const committedText = currentWords.join(' ');
-        work.spendTextLayout('committed text line measurement');
-        const committed = catalog.measureText(fontName, committedText, fontSize);
-        lines.push(committedText);
-        widths.push(committed.width);
-        retainMissingGlyphs(committed.missingGlyphs);
-        lineHeight = committed.lineHeight;
-        metricSource = committed.source;
+        commitLine(currentWords);
     }
     return {
         lines,
         widths,
+        colourLines,
         lineHeight,
         metricSource,
         missingGlyphs: [...missingGlyphs].sort((a, b) => a - b),
     };
 }
+function colourRunsForLine(catalog, fontName, line, colours, fontSize, work) {
+    if (!colours.some((colour) => colour !== undefined) || line.length === 0)
+        return [];
+    const runs = [];
+    let start = 0;
+    let offsetX = 0;
+    while (start < line.length) {
+        const colour = colours[start] ?? defaultTextColour;
+        let end = start + 1;
+        while (end < line.length && (colours[end] ?? defaultTextColour) === colour)
+            end += 1;
+        const text = line.slice(start, end);
+        work.spendTextLayout('localisation colour-run measurement');
+        const width = catalog.measureText(fontName, text, fontSize).width;
+        runs.push({ text, colour, offsetX, width });
+        offsetX += width;
+        start = end;
+    }
+    return runs;
+}
 function frameFor(element, sprite, scenario) {
     const frameCount = Math.max(1, sprite.frameCount);
     const selected = scenario.selectedFrames[element.name] ?? scenario.selectedFrames[sprite.name];
@@ -439,7 +529,8 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
             displayText = `${displayText} — ${displayText} — ${displayText}`;
         if (state === 'missing-localisation')
             displayText = `\u00a7R${rawText}_MISSING\u00a7!`;
-        displayText = visibleHoiText(displayText);
+        const visibleText = visibleHoiText(displayText);
+        displayText = visibleText.text;
         context.work.admitText(displayText, `GUI text for ${definition.name}`);
         const fontName = scalarString(property(definition.attributes, 'font', 'buttonFont'));
         const resolvedFontMetrics = catalog.resolvedFontMetrics(fontName);
@@ -450,10 +541,13 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
             16;
         const maxWidth = (scalarNumber(property(definition.attributes, 'maxWidth'), width / scale) ?? width / scale) *
             scale;
-        const wrapped = wrapText(catalog, fontName, displayText, fontSize * scale, maxWidth, context.work);
+        const wrapped = wrapText(catalog, fontName, displayText, visibleText.colours, fontSize * scale, maxWidth, context.work);
         const glyphLines = [];
         for (const line of wrapped.lines)
             glyphLines.push(await catalog.shapeText(fontName, line, fontSize * scale));
+        const colourRuns = visibleText.hasColourMarkup
+            ? wrapped.lines.map((line, index) => colourRunsForLine(catalog, fontName, line, wrapped.colourLines[index] ?? [], fontSize * scale, context.work))
+            : undefined;
         const maximumLineWidth = wrapped.widths.reduce((maximum, value) => Math.max(maximum, value), 0);
         if (width === 0)
             width = maximumLineWidth;
@@ -476,6 +570,7 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
             overflowX: width > 0 && measuredWidth > width + 0.01,
             overflowY: height > 0 && measuredHeight > height + 0.01,
             unresolvedTokens: resolved.unresolved,
+            ...(colourRuns === undefined ? {} : { colourRuns }),
         };
         if (wrapped.metricSource === 'approximation')
             addFidelity(fidelity, 'approximated', 'font_metrics', `No supplied font metrics for ${fontName ?? '<default>'}.`, definition);

package/dist/hoi4_agent_tools/gui/renderer.js

@@ -86,6 +86,22 @@ function renderText(element, toolText) {
             (glyphLine === undefined || glyphLine.source === 'deterministic-fallback'
                 ? text.lineHeight * 0.8
                 : glyphLine.baseline);
+        const colourRuns = text.colourRuns?.[index] ?? [];
+        if (colourRuns.length > 0) {
+            const runWidth = colourRuns.reduce((maximum, run) => Math.max(maximum, run.offsetX + run.width), 0);
+            const horizontalScale = runWidth > 0 && width > 0 ? width / runWidth : 1;
+            return `<g data-hoi4-colour-runs="true">${colourRuns
+                .map((run) => toolText.render(run.text, {
+                x: originX + run.offsetX * horizontalScale,
+                y: baseline,
+                fontSize: text.fontSize,
+                fill: run.colour,
+                stroke: '#12151a',
+                strokeWidth: 0.6,
+                ...(run.width > 0 ? { targetWidth: run.width * horizontalScale } : {}),
+            }))
+                .join('')}</g>`;
+        }
         if (glyphLine?.source === 'fontkit-path') {
             const horizontalScale = glyphLine.width > 0 && width > 0 ? width / glyphLine.width : 1;
             return `<g data-font-sha256="${glyphLine.sourceHash}">${glyphLine.glyphs

package/dist/hoi4_agent_tools/mcp/resources/register.js

@@ -6,7 +6,7 @@ const artifactChunkMetadataKey = 'io.github.klimpaskov/hoi4-agent-tools.artifact
 const fatalUtf8Decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
 const artifactResourceMetadata = {
     title: 'HOI4 review artifact',
-    description: 'Complete plans, diagnostics, layouts, previews, and diffs. Reads accept zero-based byte offset and positive byte length query selectors; each response reports its exact byte range and continuation URI in _meta.',
+    description: 'Complete plans, diagnostics, layouts, previews, event graphs, routes, state and scope reports, comparisons, and diffs. Reads accept zero-based byte offset and positive byte length query selectors; each response reports its exact byte range and continuation URI in _meta.',
     _meta: {
         [artifactChunkMetadataKey]: {
             version: 1,

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

@@ -1,10 +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 = 'The workspace defaults to the mod containing the MCP working directory; pass workspaceId only when selecting another configured mod. 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 function createMcpServer(engine, context = {}) {
     const server = new McpServer({
         name: PACKAGE_NAME,
@@ -12,11 +13,12 @@ export function createMcpServer(engine, context = {}) {
         websiteUrl: 'https://github.com/klimPaskov/hoi4-agent-tools',
     }, {
         capabilities: { logging: {} },
+        instructions: SERVER_INSTRUCTIONS,
     });
-    registerModsTool(server, engine, context);
     registerFocusTools(server, engine, context);
     registerGuiTools(server, engine, context);
     registerMapTools(server, engine, context);
+    registerEventTools(server, engine, context);
     registerMcpResources(server, engine, context);
     return server;
 }

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

@@ -42,24 +42,18 @@ const emptyToolDataSchema = z.object({}).strict();
 const compactPublicOperationResultSchema = z
     .object({
     status: z.enum(['ok', 'blocked', 'error']),
-    code: z.string().max(256),
-    workspaceId: z.string().max(64),
-    filesScanned: z.array(z.string().max(4096)).max(MAX_INLINE_FILES_SCANNED),
-    proposedFiles: z.array(z.string().max(1024)).max(MAX_INLINE_PROPOSED_FILES),
-    changedFiles: z.array(z.string().max(1024)).max(MAX_INLINE_CHANGED_FILES),
+    code: z.string(),
+    workspaceId: z.string(),
+    filesScanned: z.array(z.unknown()).max(MAX_INLINE_FILES_SCANNED),
+    proposedFiles: z.array(z.unknown()).max(MAX_INLINE_PROPOSED_FILES),
+    changedFiles: z.array(z.unknown()).max(MAX_INLINE_CHANGED_FILES),
     diagnostics: z.array(z.unknown()).max(MAX_INLINE_DIAGNOSTICS),
     artifacts: z.array(z.unknown()).max(MAX_INLINE_ARTIFACT_LINKS),
-    validation: z
-        .object({
-        passed: z.boolean(),
-        checks: z.array(z.unknown()).max(MAX_INLINE_VALIDATION_CHECKS),
-    })
-        .strict(),
+    validation: z.unknown(),
     blockers: z.array(z.unknown()).max(MAX_INLINE_BLOCKERS),
-    data: z.record(z.string().max(256), z.unknown()),
+    data: z.object({}).catchall(z.unknown()),
 })
-    .strict()
-    .describe('Stable operation envelope; data is tool-specific and artifacts link bulk evidence.');
+    .strict();
 /**
  * Advertise one compact operation envelope while retaining exact per-tool runtime validation.
  * The generic operation-result schema remains available for stored envelopes.