hoi4-agent-tools 2.3.0 → 2.3.4

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 2.3.4 - 2026-07-28
+
+- Bounded large game-backed event scans before workspace-wide lifecycle and helper analysis could exhaust the MCP process and close the stdio transport.
+- Added automatic focused event analysis for large workspaces, explicit deferred-analysis diagnostics, source-profile reporting, and deterministic regression coverage.
+
+## 2.3.3 - 2026-07-26
+
+- Regenerated the npm lockfile with the pinned release npm so clean installs include the patched optional native runtime packages.
+
+## 2.3.2 - 2026-07-26
+
+- Pinned patched transitive `brace-expansion` and `postcss` releases so the CI and release audit remain clean without changing the MCP Inspector surface.
+
+## 2.3.1 - 2026-07-26
+
+- Fixed large vanilla-plus-mod technology scans that could consume multiple gigabytes and leave the MCP transport open until a client timeout closed it.
+- Added automatic focused technology analysis for game-backed and large workspaces, retaining direct source evidence and helper-call indexing while deferring workspace-wide scripted-effect projections.
+
 ## 2.3.0 - 2026-07-22
 
 - Added a read-only AI and MTTH Scenario Analyzer with inspect, evaluate, sweep, simulate, sequence, compare, and render tools.

package/dist/bin/stdio.js

@@ -8,6 +8,10 @@ async function main() {
     const engine = await createEngine();
     const context = {};
     const server = createMcpServer(engine, context);
+    if (process.env.HOI4_AGENT_TOOLS_CHAOSX === '1') {
+        const { registerChaosxTools } = await import('../hoi4_agent_tools/mcp/tools/chaosx.js');
+        registerChaosxTools(server, engine, context);
+    }
     server.server.onerror = (error) => {
         const fatalInputError = error instanceof StdioFrameLimitError || error instanceof StdioInvalidUtf8Error;
         const rejectedMessage = error instanceof StdioInvalidMessageError;

package/dist/hoi4_agent_tools/event/algorithms.js

@@ -1,4 +1,4 @@
-import { compareCodeUnits } from '../core/canonical.js';
+import { compareCodeUnits, hashCanonical } from '../core/canonical.js';
 import { EventAnalysisBudget } from './limits.js';
 import { iterativeStronglyConnectedComponents } from './scc.js';
 function sortedUnique(values) {
@@ -41,6 +41,178 @@ function edgeMaps(edges) {
     }
     return { outgoing, incoming };
 }
+function helperName(node) {
+    const name = node.metadata.name;
+    if (typeof name === 'string')
+        return name;
+    return node.label || node.id.replace(/^helper:/u, '');
+}
+function collapsedHelperEdge(path, helperStack, from, to) {
+    const first = path[0];
+    const last = path.at(-1);
+    if (helperStack.length === 0)
+        return first;
+    return {
+        id: `edge:lazy-helper-projection:${hashCanonical({
+            from,
+            to,
+            edges: path.map(({ id }) => id),
+        }).slice(0, 32)}`,
+        from,
+        to,
+        reason: 'scripted_effect_expansion',
+        conditions: path.flatMap(({ conditions }) => conditions),
+        helperStack: [...helperStack],
+        location: first.location,
+        provenance: path.flatMap(({ provenance }) => provenance),
+        confidence: last.confidence,
+        derived: true,
+        ...(last.timing === undefined ? {} : { timing: last.timing }),
+        ...(last.weight === undefined ? {} : { weight: last.weight }),
+        ...(last.scope === undefined ? {} : { scope: last.scope }),
+        metadata: { structuralEdgeIds: path.map(({ id }) => id) },
+    };
+}
+/**
+ * Build only the helper projections reached by one bounded trace. Full-workspace
+ * helper materialisation is useful for broad reports, but it is unnecessarily
+ * expensive when an agent asks for one route in a large installed game.
+ */
+function lazyCollapsedEdges(graph, nodeId, direction, maps, maximumPaths, signal) {
+    const nodes = nodeMap(graph);
+    const retained = new Map();
+    let pathVisits = 0;
+    const add = (edge) => {
+        retained.set(edge.id, edge);
+    };
+    const downstream = (edge, path, stack, visited) => {
+        signal?.throwIfAborted();
+        if (++pathVisits > maximumPaths)
+            return;
+        if (path.length > 64)
+            return;
+        const target = nodes.get(edge.to);
+        if (target?.kind !== 'helper') {
+            add(collapsedHelperEdge(path, stack, nodeId, edge.to));
+            return;
+        }
+        if (visited.has(target.id))
+            return;
+        for (const next of maps.outgoing.get(target.id) ?? []) {
+            downstream(next, [...path, next], [...stack, helperName(target)], new Set([...visited, target.id]));
+        }
+    };
+    const upstream = (edge, path, stack, visited) => {
+        signal?.throwIfAborted();
+        if (++pathVisits > maximumPaths)
+            return;
+        if (path.length > 64)
+            return;
+        const source = nodes.get(edge.from);
+        if (source?.kind !== 'helper') {
+            const forwardPath = [...path].reverse();
+            add(collapsedHelperEdge(forwardPath, [...stack].reverse(), edge.from, nodeId));
+            return;
+        }
+        if (visited.has(source.id))
+            return;
+        for (const previous of maps.incoming.get(source.id) ?? []) {
+            upstream(previous, [...path, previous], [...stack, helperName(source)], new Set([...visited, source.id]));
+        }
+    };
+    if (direction !== 'upstream') {
+        for (const edge of maps.outgoing.get(nodeId) ?? [])
+            downstream(edge, [edge], [], new Set());
+    }
+    if (direction !== 'downstream') {
+        for (const edge of maps.incoming.get(nodeId) ?? [])
+            upstream(edge, [edge], [], new Set());
+    }
+    return [...retained.values()].sort((left, right) => compareCodeUnits(left.id, right.id));
+}
+function traceCollapsedHelpers(graph, starts, boundary, signal) {
+    const byId = nodeMap(graph);
+    const maps = edgeMaps(graph.edges.filter(({ derived }) => !derived));
+    const edgeCache = new Map();
+    const edgesFor = (nodeId) => {
+        const key = `${nodeId}\0${boundary.direction}`;
+        const cached = edgeCache.get(key);
+        if (cached !== undefined)
+            return cached;
+        const edges = lazyCollapsedEdges(graph, nodeId, boundary.direction, maps, Math.max(256, boundary.maxEdges * 2), signal);
+        edgeCache.set(key, edges);
+        return edges;
+    };
+    const depthByNode = new Map(starts.map((id) => [id, 0]));
+    const queue = [...starts];
+    const retainedEdges = new Map();
+    const boundaryNodes = new Set();
+    let truncated = false;
+    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 = edgesFor(current);
+        if (depth >= boundary.maxDepth) {
+            if (nextEdges.length > 0) {
+                boundaryNodes.add(current);
+                truncated = true;
+            }
+            continue;
+        }
+        for (const edge of nextEdges) {
+            if (retainedEdges.size >= boundary.maxEdges) {
+                boundaryNodes.add(current);
+                truncated = true;
+                break;
+            }
+            const next = boundary.direction === 'upstream'
+                ? edge.from
+                : boundary.direction === 'downstream'
+                    ? edge.to
+                    : edge.from === current
+                        ? edge.to
+                        : edge.from;
+            const known = depthByNode.has(next);
+            if (!known && depthByNode.size >= boundary.maxNodes) {
+                boundaryNodes.add(current);
+                truncated = true;
+                continue;
+            }
+            retainedEdges.set(edge.id, edge);
+            if (!known) {
+                depthByNode.set(next, depth + 1);
+                queue.push(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,
+    };
+}
 function edgesForDirection(nodeId, direction, maps) {
     const results = [];
     if (direction !== 'upstream') {
@@ -58,6 +230,11 @@ export function traceEventGraph(graph, startNodeIds, boundary, signal) {
     const byId = nodeMap(graph);
     const resolvedStarts = sortedUnique(startNodeIds).filter((id) => byId.has(id));
     const starts = resolvedStarts.slice(0, Math.max(0, boundary.maxNodes));
+    if (!boundary.expandHelpers &&
+        !graph.edges.some(({ derived }) => derived) &&
+        starts.every((id) => byId.get(id)?.kind !== 'helper')) {
+        return traceCollapsedHelpers(graph, starts, boundary, signal);
+    }
     const edges = eventFlowEdges(graph, boundary.expandHelpers);
     const maps = edgeMaps(edges);
     const depthByNode = new Map(starts.map((id) => [id, 0]));

package/dist/hoi4_agent_tools/event/graph.js

@@ -29,6 +29,14 @@ function activeFiles(snapshot) {
         !/(?:^|\/)(?:supply_nodes|railways|buildings|unitstacks|weatherpositions)\.txt$/iu.test(relativePath.replaceAll('\\', '/')))
         .sort((left, right) => compareCodeUnits(left.displayPath, right.displayPath));
 }
+const EVENT_SETUP_CALL_PATTERN = /\b(?:country_event|news_event|state_event|unit_leader_event|operative_leader_event|fire_event|event)\s*=/iu;
+function shouldAnalyzeEventFile(file) {
+    const sourcePath = file.relativePath.replaceAll('\\', '/').toLowerCase();
+    if (!sourcePath.startsWith('history/countries/') && !sourcePath.startsWith('history/states/')) {
+        return true;
+    }
+    return EVENT_SETUP_CALL_PATTERN.test(file.bytes.toString('utf8'));
+}
 function catalogFor(snapshot) {
     const unshadowedEventSymbols = snapshot.index
         .findAll('event')
@@ -1444,6 +1452,8 @@ function analyzeFragments(snapshot, files, catalog, options, budget) {
     const fragments = [];
     for (const file of files) {
         budget.spend('source_fragment');
+        if (!shouldAnalyzeEventFile(file))
+            continue;
         if (snapshot.index.isSourceSkipped(file.displayPath))
             continue;
         const cacheKey = eventSemanticFragmentCacheKey(file, catalog.fingerprint);
@@ -1560,14 +1570,31 @@ export function buildEventGraph(snapshot, options = {}) {
     graph.edges = stableUnique(graph.edges);
     graph.stateAccesses = stableUnique(graph.stateAccesses);
     graph.unresolved = stableUnique(graph.unresolved);
-    const stateLinks = stateLinksFor(graph, budget);
-    duplicateAndReferenceIssues(graph);
-    unresolvedIssues(graph);
-    structuralCallIssues(graph, budget);
-    localisationIssues(graph);
-    stateLifecycleIssues(graph, stateLinks, budget);
-    unreachableIssues(graph, budget);
-    normalizeIssueSubjects(graph);
+    const focused = options.analysisMode === 'focused';
+    if (focused) {
+        graph.unresolved.push({
+            id: 'event-analysis-focused-boundary',
+            kind: 'partial_source',
+            expression: 'workspace-wide event helper projections and lifecycle diagnostics',
+            confidence: 'unresolved',
+            blockers: [
+                {
+                    code: 'EVENT_FOCUSED_ANALYSIS_DEFERRED',
+                    message: 'Large event workspaces defer workspace-wide helper projections and lifecycle passes; direct source evidence remains available.',
+                },
+            ],
+        });
+    }
+    const stateLinks = focused ? [] : stateLinksFor(graph, budget);
+    if (!focused) {
+        duplicateAndReferenceIssues(graph);
+        unresolvedIssues(graph);
+        structuralCallIssues(graph, budget);
+        localisationIssues(graph);
+        stateLifecycleIssues(graph, stateLinks, budget);
+        unreachableIssues(graph, budget);
+        normalizeIssueSubjects(graph);
+    }
     graph.issues = stableIssues(graph.issues);
     assertGraphLimit(graph.nodes.length, EVENT_GRAPH_MAX_NODES, 'EVENT_NODE_LIMIT', 'node count');
     assertGraphLimit(graph.edges.length, EVENT_GRAPH_MAX_EDGES, 'EVENT_EDGE_LIMIT', 'edge count');
@@ -1577,7 +1604,8 @@ export function buildEventGraph(snapshot, options = {}) {
     assertGraphLimit(graph.unresolved.length, EVENT_GRAPH_MAX_UNRESOLVED, 'EVENT_UNRESOLVED_LIMIT', 'unresolved-analysis count');
     budget.check();
     const diagnostics = sortDiagnostics([...snapshot.diagnostics, ...partial.diagnostics]);
-    const complete = snapshot.complete &&
+    const complete = !focused &&
+        snapshot.complete &&
         graph.unresolved.length === 0 &&
         !graph.issues.some(({ classification, severity }) => classification === 'unresolved_analysis' || severity === 'blocker');
     const nodes = sortNodes(graph.nodes);
@@ -1588,6 +1616,7 @@ export function buildEventGraph(snapshot, options = {}) {
     return {
         schemaVersion: EVENT_GRAPH_SCHEMA_VERSION,
         parserVersion: EVENT_GRAPH_PARSER_VERSION,
+        analysisMode: options.analysisMode ?? 'full',
         workspaceId: snapshot.workspaceId,
         workspaceIdentity: options.workspaceIdentity ?? hashCanonical({ workspaceId: snapshot.workspaceId }),
         revision: snapshot.revision,

package/dist/hoi4_agent_tools/event/limits.js

@@ -4,7 +4,10 @@ export const EVENT_GRAPH_MAX_EDGES = 500_000;
 export const EVENT_GRAPH_MAX_STATE_ACCESSES = 250_000;
 export const EVENT_GRAPH_MAX_STATE_LINKS = 250_000;
 export const EVENT_GRAPH_MAX_STATE_LINK_CANDIDATES = 500_000;
-export const EVENT_GRAPH_MAX_ISSUES = 20_000;
+// Installed-game scans can legitimately produce more than twenty thousand source-linked
+// findings before an agent narrows the query. Keep the graph bounded, but do not reject a
+// complete large workspace merely because its diagnostics are numerous.
+export const EVENT_GRAPH_MAX_ISSUES = 100_000;
 export const EVENT_GRAPH_MAX_UNRESOLVED = 50_000;
 export const EVENT_GRAPH_MAX_HELPER_DEPTH = 64;
 export const EVENT_GRAPH_MAX_HELPER_PROJECTIONS = 200_000;