hoi4-agent-tools 1.1.0 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 2.0.0 - 2026-07-15
+
+- Removed the workspace inventory tool and made the current mod implicit for local MCP calls.
+- Starting the server inside any mod now works without a config file or per-mod setup command.
+- Updated the published client examples, Registry metadata, and installation verification for the twelve-tool surface.
+- Rendered unresolved scripted localisation values as `[X]` and applied supported HOI4 `§` text colours in offline GUI previews.
+
+## 1.2.0 - 2026-07-13
+
+- Added a read-only Event Chain Viewer for scanning, tracing, explaining, linting, rendering, and comparing large HOI4 event chains.
+- Kept the event surface to three tools with seven inspect modes and linked authoritative graph artifacts, keeping the public surface to twelve tools within the fixed discovery budget. Local calls now resolve the mod containing the MCP working directory.
+- Added event workflow documentation, package and Registry metadata, and project-owned acceptance coverage for more than 300 event definitions.
+- Reconfirmed MCP protocol `2025-11-25`, TypeScript SDK 1.29.0, Registry schema `2025-12-11`, and Registry publisher 1.7.9 for this release.
+
+## 1.1.1 - 2026-07-13
+
+- Replaced the repository About text with a direct description of the focus-tree, GUI, and map tools.
+- Simplified the README introduction and HTTP summary so operational safeguards remain in their dedicated documentation.
+
 ## 1.1.0 - 2026-07-12
 
 - Added plan-free `compact` rewrites for existing national focus trees while retaining authored mode for complete plans and new trees.

package/README.md

@@ -1,23 +1,23 @@
 # HOI4 Agent Tools
 
-HOI4 Agent Tools is an MCP server that helps coding agents inspect, create, and clean up Hearts of Iron IV focus trees, scripted GUIs, and maps. It works directly with configured mod folders and produces offline renders for review. It does not launch or control the game.
+HOI4 Agent Tools is an MCP server for coding agents to analyze Hearts of Iron IV event chains and inspect, create, or clean up focus trees, scripted GUIs, and maps. Start it in a mod folder and it works there immediately, with offline renders for review.
 
 ## What it does
 
 - Focus trees: inspect structure and references, render layouts, create trees, and reorganize existing branches.
 - Scripted GUIs: trace GUI, GFX, scripted-GUI, and localisation links; render states; create or repair interface source.
 - Maps: inspect provinces, states, regions, adjacency, supply, and railways; render layers; create and repair exact map data.
+- Event chains: scan definitions and call sites, trace routes and state flow, lint references, render graphs, and compare revisions without editing event source.
 
 ## Setup
 
 Requires Node.js 22 or 24.
 
 ```bash
-npm install --global hoi4-agent-tools@1.1.0
-hoi4-agent-tools-setup --init
+npm install --global hoi4-agent-tools@2.0.0
 ```
 
-`--init` discovers the usual HOI4 game and mod locations and writes the default per-user configuration. No `HOI4_AGENT_CONFIG` environment variable is needed. For custom paths, multiple mod roots, or a custom config location, see [Setup](docs/setup.md).
+Start the MCP with its working directory set to the mod you are editing. No config or per-mod registration is required: the server finds that mod automatically. Run `hoi4-agent-tools-setup --init` only when you want persistent discovery for several mod roots, a custom game path, or a remote deployment; see [Setup](docs/setup.md).
 
 ## Connect your agent
 
@@ -29,18 +29,20 @@ Paste the printed Codex or generic global-install entry into your MCP client, th
 
 ## Tools
 
-| Tool                 | Purpose                                                          |
-| -------------------- | ---------------------------------------------------------------- |
-| `hoi4.mods`          | List the writable mods available to the coding agent.            |
-| `hoi4.focus_inspect` | Read focus trees and report structural or reference problems.    |
-| `hoi4.focus_render`  | Render an existing focus tree or continuous palette.             |
-| `hoi4.focus_rewrite` | Create or update a focus tree.                                   |
-| `hoi4.gui_inspect`   | Read a scripted GUI and its linked assets and logic.             |
-| `hoi4.gui_render`    | Render GUI states and resolutions offline.                       |
-| `hoi4.gui_rewrite`   | Create or update a GUI source package.                           |
-| `hoi4.map_inspect`   | Read map, state, province, region, supply, and railway data.     |
-| `hoi4.map_render`    | Render map layers and overlays.                                  |
-| `hoi4.map_rewrite`   | Create or update map data from an ordered list of exact changes. |
+| Tool                 | Purpose                                                                                 |
+| -------------------- | --------------------------------------------------------------------------------------- |
+| `hoi4.focus_inspect` | Read focus trees and report structural or reference problems.                           |
+| `hoi4.focus_render`  | Render an existing focus tree or continuous palette.                                    |
+| `hoi4.focus_rewrite` | Create or update a focus tree.                                                          |
+| `hoi4.gui_inspect`   | Read a scripted GUI and its linked assets and logic.                                    |
+| `hoi4.gui_render`    | Render GUI states and resolutions offline.                                              |
+| `hoi4.gui_rewrite`   | Create or update a GUI source package.                                                  |
+| `hoi4.map_inspect`   | Read map, state, province, region, supply, and railway data.                            |
+| `hoi4.map_render`    | Render map layers and overlays.                                                         |
+| `hoi4.map_rewrite`   | Create or update map data from an ordered list of exact changes.                        |
+| `hoi4.event_inspect` | Scan, trace, explain, lint, or assess event chains and their state flow.                |
+| `hoi4.event_render`  | Render source-linked event routes, options, timing, state, scope, and unresolved edges. |
+| `hoi4.event_compare` | Compare event-chain topology and diagnostics between revisions.                         |
 
 Large outputs are linked `hoi4-agent://` resources. For resources over 1 MiB, follow the `continuationUri` returned in `_meta` until it is `null`; clients may also request byte ranges with `?offset=<bytes>&length=<bytes>`.
 
@@ -48,7 +50,7 @@ Large outputs are linked `hoi4-agent://` resources. For resources over 1 MiB, fo
 
 HOI4 Agent Tools provides HOI4 domain operations; it does not register MCP prompts, replace repository instructions such as `AGENTS.md`, manage skills or plans, or start subagents. The coding agent decides when to call it as part of its existing workflow.
 
-Connecting and listing tools does not scan mod source. Compact tool schemas and linked resources keep large diagnostics, renders, and diffs out of the agent's working context until needed. Only `hoi4.*_rewrite` calls edit mod source.
+Connecting and listing tools does not scan mod source. Compact tool schemas and linked resources keep large diagnostics, renders, and diffs out of the agent's working context until needed. The event tools are read-only; only `hoi4.*_rewrite` calls edit mod source.
 
 ## Create or clean content
 
@@ -57,10 +59,11 @@ Ask your agent in normal task language. A typical workflow is inspect, render, r
 - Focus trees: "Create a complete national focus tree for this route specification," or "Compact this existing tree into a balanced, readable layout." Existing trees can use a plan-free compact reflow; new trees use a complete plan. See [Focus trees](docs/focus.md).
 - Scripted GUIs: "Create a scripted GUI for this mechanic," or "Render this window at common resolutions and fix clipping, missing assets, and click-region conflicts." See [Scripted GUIs](docs/gui.md).
 - Maps: "Create a state from these exact provinces," or "Inspect this state and split these provinces while keeping supply and railway references valid." See [Maps](docs/map.md).
+- Event chains: "Trace every route from this event and explain where its flags and variables change," or "Compare the workspace event graph with its previous revision and render the affected routes." See [Event chains](docs/events.md).
 
 ## HTTP
 
-Rewrites validate and apply in one call. The installed game is never changed, and an interrupted multi-file rewrite is recovered automatically. Local MCP clients should use stdio; shared or remote deployments use the controls described in [HTTP](docs/http.md).
+Use stdio for local MCP clients. For shared or remote deployments, see [HTTP](docs/http.md).
 
 ## Development
 

package/dist/hoi4_agent_tools/core/engine.js

@@ -33,7 +33,15 @@ function defaultPatterns(workspace) {
             'common/characters/**/*.txt',
             'common/scripted_effects/**/*.txt',
             'common/scripted_triggers/**/*.txt',
+            'common/on_actions/**/*.txt',
+            'common/operations/**/*.txt',
+            'common/raids/**/*.txt',
+            'common/bop/**/*.txt',
+            'common/resistance_compliance_modifiers/**/*.txt',
+            'common/special_projects/**/*.txt',
             'events/**/*.txt',
+            'history/countries/**/*.txt',
+            'history/states/**/*.txt',
             ...under(roots.states, '**/*.txt'),
             // Binary rasters and positional data tables are domain-selected by Agent
             // Nudger. The shared symbol scan retains only map sources it can index.
@@ -183,6 +191,10 @@ export class CoreEngine {
             flight.controller.abort();
         }
     }
+    /** Monotonic cache generation used by domain services to invalidate derived snapshots. */
+    generation(workspaceId) {
+        return this.#scanGenerations.get(workspaceId) ?? 0;
+    }
     awaitScanFlight(requestKey, flight, signal) {
         signal?.throwIfAborted();
         flight.waiters += 1;

package/dist/hoi4_agent_tools/core/workspace.js

@@ -4,6 +4,8 @@ import { WORKSPACE_MAX_REGISTRATIONS, workspaceRegistrationSchema, } from './con
 import { compareCodeUnits, hashCanonical, sha256Bytes } from './canonical.js';
 import { ServiceError } from './result.js';
 import { ServerState } from './server-state.js';
+/** Omitted MCP workspace arguments resolve to the mod containing the server cwd. */
+export const CURRENT_WORKSPACE_ID = 'current';
 async function exists(value, signal) {
     signal?.throwIfAborted();
     try {
@@ -185,6 +187,9 @@ export class WorkspaceResolver {
             }
         }
         for (const configured of configuration.workspaces) {
+            if (configured.id === CURRENT_WORKSPACE_ID) {
+                throw new ServiceError('WORKSPACE_ID_RESERVED', `Workspace ID is reserved for the current working mod: ${CURRENT_WORKSPACE_ID}`);
+            }
             const registration = resolver.withGlobalWorkspaceDefaults(configured);
             const workspace = await resolver.resolveRegistration(registration);
             if (resolver.#byId.has(workspace.id)) {
@@ -203,6 +208,28 @@ export class WorkspaceResolver {
     config() {
         return this.configuration;
     }
+    /** Resolve the implicit workspace used by local coding-agent calls. */
+    resolveCurrentWorkspaceId(principal) {
+        const workspaces = this.list(principal).filter(({ registration }) => registration.kind === 'mod');
+        if (workspaces.length === 0) {
+            throw new ServiceError('WORKSPACE_CONTEXT_NOT_FOUND', 'No writable mod workspace is configured for the MCP server');
+        }
+        const currentDirectory = path.normalize(process.cwd());
+        const containing = workspaces.filter((workspace) => isWithin(workspace.modRoot, currentDirectory));
+        if (containing.length === 1)
+            return containing[0].id;
+        if (containing.length > 1) {
+            throw new ServiceError('WORKSPACE_CONTEXT_AMBIGUOUS', 'The MCP working directory is inside more than one writable mod workspace', { currentDirectory });
+        }
+        if (workspaces.length === 1)
+            return workspaces[0].id;
+        throw new ServiceError('WORKSPACE_CONTEXT_REQUIRED', 'The MCP working directory does not identify one writable mod workspace', { currentDirectory, workspaceIds: workspaces.map(({ id }) => id) });
+    }
+    resolveWorkspaceId(workspaceId, principal) {
+        return workspaceId === CURRENT_WORKSPACE_ID
+            ? this.resolveCurrentWorkspaceId(principal)
+            : workspaceId;
+    }
     serverState() {
         return this.#serverState;
     }
@@ -276,15 +303,16 @@ export class WorkspaceResolver {
             .sort((a, b) => compareCodeUnits(a.id, b.id));
     }
     get(workspaceId, principal) {
-        if (principal !== undefined && !this.allowedWorkspaceIds(principal).has(workspaceId)) {
+        const resolvedWorkspaceId = this.resolveWorkspaceId(workspaceId, principal);
+        if (principal !== undefined && !this.allowedWorkspaceIds(principal).has(resolvedWorkspaceId)) {
             throw new ServiceError('WORKSPACE_INACCESSIBLE', 'Workspace is unavailable to the authenticated principal');
         }
-        const workspace = this.#byId.get(workspaceId);
+        const workspace = this.#byId.get(resolvedWorkspaceId);
         if (workspace === undefined) {
             if (principal !== undefined) {
                 throw new ServiceError('WORKSPACE_INACCESSIBLE', 'Workspace is unavailable to the authenticated principal');
             }
-            throw new ServiceError('WORKSPACE_NOT_REGISTERED', `Workspace is not registered: ${workspaceId}`);
+            throw new ServiceError('WORKSPACE_NOT_REGISTERED', `Workspace is not registered: ${resolvedWorkspaceId}`);
         }
         return workspace;
     }

package/dist/hoi4_agent_tools/event/algorithms.js

@@ -0,0 +1,208 @@
+import { compareCodeUnits } from '../core/canonical.js';
+import { EventAnalysisBudget } from './limits.js';
+import { iterativeStronglyConnectedComponents } from './scc.js';
+function sortedUnique(values) {
+    return [...new Set(values)].sort(compareCodeUnits);
+}
+function nodeMap(graph) {
+    return new Map(graph.nodes.map((node) => [node.id, node]));
+}
+/**
+ * Select either the structural helper graph or its event-to-event projection.
+ * Direct, option, entry, unresolved, and terminal edges remain visible in both.
+ */
+export function eventFlowEdges(graph, expandHelpers) {
+    const nodes = nodeMap(graph);
+    return graph.edges
+        .filter((edge) => {
+        if (expandHelpers)
+            return !edge.derived;
+        if (edge.derived)
+            return true;
+        const from = nodes.get(edge.from);
+        const to = nodes.get(edge.to);
+        return from?.kind !== 'helper' && to?.kind !== 'helper';
+    })
+        .sort((left, right) => compareCodeUnits(left.id, right.id));
+}
+function edgeMaps(edges) {
+    const outgoing = new Map();
+    const incoming = new Map();
+    for (const edge of edges) {
+        const from = outgoing.get(edge.from) ?? [];
+        from.push(edge);
+        outgoing.set(edge.from, from);
+        const to = incoming.get(edge.to) ?? [];
+        to.push(edge);
+        incoming.set(edge.to, to);
+    }
+    for (const values of [...outgoing.values(), ...incoming.values()]) {
+        values.sort((left, right) => compareCodeUnits(left.id, right.id));
+    }
+    return { outgoing, incoming };
+}
+function edgesForDirection(nodeId, direction, maps) {
+    const results = [];
+    if (direction !== 'upstream') {
+        for (const edge of maps.outgoing.get(nodeId) ?? [])
+            results.push({ edge, next: edge.to });
+    }
+    if (direction !== 'downstream') {
+        for (const edge of maps.incoming.get(nodeId) ?? [])
+            results.push({ edge, next: edge.from });
+    }
+    return results.sort((left, right) => compareCodeUnits(left.next, right.next) || compareCodeUnits(left.edge.id, right.edge.id));
+}
+export function traceEventGraph(graph, startNodeIds, boundary, signal) {
+    signal?.throwIfAborted();
+    const byId = nodeMap(graph);
+    const resolvedStarts = sortedUnique(startNodeIds).filter((id) => byId.has(id));
+    const starts = resolvedStarts.slice(0, Math.max(0, boundary.maxNodes));
+    const edges = eventFlowEdges(graph, boundary.expandHelpers);
+    const maps = edgeMaps(edges);
+    const depthByNode = new Map(starts.map((id) => [id, 0]));
+    const queue = [...starts];
+    const retainedEdges = new Map();
+    const boundaryNodes = new Set(resolvedStarts.length > starts.length ? starts : []);
+    let truncated = resolvedStarts.length > starts.length;
+    let cursor = 0;
+    while (cursor < queue.length) {
+        if ((cursor & 255) === 0)
+            signal?.throwIfAborted();
+        const current = queue[cursor++];
+        const depth = depthByNode.get(current) ?? 0;
+        const nextEdges = edgesForDirection(current, boundary.direction, maps);
+        if (depth >= boundary.maxDepth) {
+            if (nextEdges.length > 0) {
+                boundaryNodes.add(current);
+                truncated = true;
+            }
+            continue;
+        }
+        for (const candidate of nextEdges) {
+            if (retainedEdges.size >= boundary.maxEdges) {
+                boundaryNodes.add(current);
+                truncated = true;
+                break;
+            }
+            const known = depthByNode.has(candidate.next);
+            if (!known && depthByNode.size >= boundary.maxNodes) {
+                boundaryNodes.add(current);
+                truncated = true;
+                continue;
+            }
+            retainedEdges.set(candidate.edge.id, candidate.edge);
+            if (!known) {
+                depthByNode.set(candidate.next, depth + 1);
+                queue.push(candidate.next);
+            }
+        }
+    }
+    const retainedNodes = [...depthByNode.keys()]
+        .flatMap((id) => {
+        const node = byId.get(id);
+        return node === undefined ? [] : [node];
+    })
+        .sort((left, right) => compareCodeUnits(left.id, right.id));
+    const layers = [...new Set(depthByNode.values())]
+        .sort((left, right) => left - right)
+        .map((depth) => ({
+        depth,
+        nodeIds: [...depthByNode.entries()]
+            .filter(([, value]) => value === depth)
+            .map(([id]) => id)
+            .sort(compareCodeUnits),
+    }));
+    return {
+        startNodeIds: starts,
+        nodes: retainedNodes,
+        edges: [...retainedEdges.values()].sort((left, right) => compareCodeUnits(left.id, right.id)),
+        layers,
+        boundary,
+        boundaryNodeIds: [...boundaryNodes].sort(compareCodeUnits),
+        truncated,
+    };
+}
+export function shortestEventPath(graph, fromNodeIds, toNodeIds, options, signal) {
+    signal?.throwIfAborted();
+    const nodes = nodeMap(graph);
+    const starts = sortedUnique(fromNodeIds).filter((id) => nodes.has(id));
+    const targets = new Set(toNodeIds.filter((id) => nodes.has(id)));
+    const maps = edgeMaps(eventFlowEdges(graph, options.expandHelpers));
+    const queue = starts.map((nodeId) => ({ nodeId, depth: 0 }));
+    const visited = new Set(starts);
+    const predecessor = new Map();
+    let cursor = 0;
+    let found = starts.find((id) => targets.has(id));
+    while (found === undefined && cursor < queue.length) {
+        if ((cursor & 255) === 0)
+            signal?.throwIfAborted();
+        const current = queue[cursor++];
+        if (current.depth >= options.maxDepth)
+            continue;
+        for (const edge of maps.outgoing.get(current.nodeId) ?? []) {
+            if (visited.has(edge.to))
+                continue;
+            if (visited.size >= options.maxNodes)
+                return undefined;
+            visited.add(edge.to);
+            predecessor.set(edge.to, { nodeId: current.nodeId, edge });
+            if (targets.has(edge.to)) {
+                found = edge.to;
+                break;
+            }
+            queue.push({ nodeId: edge.to, depth: current.depth + 1 });
+        }
+    }
+    if (found === undefined)
+        return undefined;
+    const nodeIds = [found];
+    const pathEdges = [];
+    let cursorNode = found;
+    while (!starts.includes(cursorNode)) {
+        const previous = predecessor.get(cursorNode);
+        if (previous === undefined)
+            return undefined;
+        pathEdges.push(previous.edge);
+        cursorNode = previous.nodeId;
+        nodeIds.push(cursorNode);
+    }
+    nodeIds.reverse();
+    pathEdges.reverse();
+    return { nodeIds, edges: pathEdges };
+}
+/** Stable, bounded iterative Tarjan SCCs over the selected flow projection. */
+export function eventStronglyConnectedComponents(graph, expandHelpers = false, selectedNodeIds, signal) {
+    signal?.throwIfAborted();
+    const retainedNodes = graph.nodes
+        .filter((node) => selectedNodeIds === undefined || selectedNodeIds.has(node.id))
+        .map(({ id }) => id)
+        .sort(compareCodeUnits);
+    const retained = new Set(retainedNodes);
+    const edges = eventFlowEdges(graph, expandHelpers).filter(({ from, to }) => retained.has(from) && retained.has(to));
+    const outgoing = edgeMaps(edges).outgoing;
+    const adjacency = new Map([...outgoing].map(([nodeId, values]) => [nodeId, values.map(({ to }) => to)]));
+    const budget = new EventAnalysisBudget(signal);
+    const components = iterativeStronglyConnectedComponents(retainedNodes, adjacency, () => budget.spend('strongly_connected_components'));
+    budget.check();
+    return components
+        .map((nodeIds) => {
+        const members = new Set(nodeIds);
+        const selfLoop = edges.some(({ from, to }) => from === to && members.has(from));
+        return {
+            id: `scc:${nodeIds.join('|')}`,
+            nodeIds,
+            cyclic: nodeIds.length > 1 || selfLoop,
+        };
+    })
+        .sort((left, right) => compareCodeUnits(left.id, right.id));
+}
+export function reachableEventNodeIds(graph, startNodeIds, direction, expandHelpers = false, signal) {
+    return traceEventGraph(graph, startNodeIds, {
+        maxDepth: Number.MAX_SAFE_INTEGER,
+        maxNodes: Math.max(1, graph.nodes.length),
+        maxEdges: Math.max(1, graph.edges.length),
+        direction,
+        expandHelpers,
+    }, signal).nodes.map(({ id }) => id);
+}