hoi4-agent-tools 2.2.0 → 2.3.3

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 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.
+- Added versioned adapters for event MTTH and options, decisions, missions, focuses, technologies, doctrines, direct random chance, `random_list`, supported AI strategy factors, and declared custom weighted pools without treating unlike HOI4 systems as one probability formula.
+- Added exact and bounded scenario evaluation, AST-path provenance, nested-random path probabilities, ranges, alternatives, distributions, numeric correlations, configurable diagnostics, named acceptance bands, and explicit external-factor support.
+- Added threshold-aware sweeps with trigger-adjacent breakpoints, local elasticities, pairwise interactions, rank reversals, cliffs, and missed target bands.
+- Added constant-memory Latin hypercube and seeded pseudo-random simulation, global input importance, Wilson intervals, and discrete daily-hazard MTTH samples with bounded quantile retention and uncertainty evidence.
+- Added declared-manifest sequence analysis for recovery, caps, cooldowns, removal, resets, timer changes, terminal states, and per-category outcomes without executing effects or inferring campaign state.
+- Added scenario-hash-bound deterministic ranking, matrix, waterfall, timing-survival, sensitivity, threshold, sequence, comparison, and unresolved renders with scenario, candidate, and metric filters.
+- Added fail-closed installed-game build verification for the versioned probability adapters.
+- Added generated public schemas, callable examples, source evidence, deterministic artifacts, and a project-owned fixture containing more than 150 weighted blocks, 250 scenarios, exact expectations, unresolved cases, and a stateful pool.
+- Verified analyzer discovery and workflows over stdio and authenticated Streamable HTTP, package installation, resource retrieval, cancellation, stale-result handling, workspace isolation, large candidate pools, and the official MCP Inspector.
+- Expanded event-graph capacity for installed-game and large-mod analysis beyond 100,000 nodes while retaining bounded artifact validation.
+- Reconfirmed MCP protocol `2025-11-25`, TypeScript SDK 1.29.0, Inspector 1.0.0, Registry schema `2025-12-11`, and Registry publisher 1.8.0 for this release.
+
 ## 2.2.0 - 2026-07-22
 
 - Added a read-only Technology Tree Viewer for classic technologies, legacy and current doctrines, source folder layouts, prerequisites, exclusive choices, categories, tags, unlocks, bonuses, grants, metadata, localisation, icons, and cross-file references.

package/README.md

@@ -1,6 +1,6 @@
 # HOI4 Agent Tools
 
-HOI4 Agent Tools is an MCP server for coding agents to understand Hearts of Iron IV event chains and technology systems and to 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.
+HOI4 Agent Tools is an MCP server for coding agents to understand Hearts of Iron IV event chains, technology systems, AI weights, and MTTH timing and to 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
 
@@ -9,6 +9,7 @@ HOI4 Agent Tools is an MCP server for coding agents to understand Hearts of Iron
 - 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.
 - Technology trees: reconstruct technology and doctrine paths, folder layouts, unlocks, bonuses, grants, metadata, assets, and structural changes.
+- AI and MTTH: evaluate weighted choices and timing across explicit scenarios, sweep uncertain inputs, simulate distributions, compare patches, and analyze declared stateful pools.
 
 ## Setup
 
@@ -30,32 +31,39 @@ Paste the printed Codex or generic global-install entry into your MCP client, th
 
 ## Tools
 
-| Tool                 | Purpose                                                                                 |
-| -------------------- | --------------------------------------------------------------------------------------- |
-| `hoi4.focus_inspect` | Read focus trees and report structural or reference problems.                           |
-| `hoi4.focus_render`  | Produce fast HTML, SVG, JSON, and source-linked layout artifacts.                       |
-| `hoi4.focus_raster`  | Produce a high-fidelity PNG review with decoded source icons.                           |
-| `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.                         |
-| `hoi4.tech_inspect`  | Scan, trace, explain, lint, and assess technology and doctrine systems.                 |
-| `hoi4.tech_render`   | Render source layouts, dependency paths, unlocks, grants, metadata, and asset coverage. |
-| `hoi4.tech_compare`  | Compare technology graphs, placements, references, diagnostics, and source overlays.    |
+| Tool                        | Purpose                                                                                 |
+| --------------------------- | --------------------------------------------------------------------------------------- |
+| `hoi4.focus_inspect`        | Read focus trees and report structural or reference problems.                           |
+| `hoi4.focus_render`         | Produce fast HTML, SVG, JSON, and source-linked layout artifacts.                       |
+| `hoi4.focus_raster`         | Produce a high-fidelity PNG review with decoded source icons.                           |
+| `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.                         |
+| `hoi4.tech_inspect`         | Scan, trace, explain, lint, and assess technology and doctrine systems.                 |
+| `hoi4.tech_render`          | Render source layouts, dependency paths, unlocks, grants, metadata, and asset coverage. |
+| `hoi4.tech_compare`         | Compare technology graphs, placements, references, diagnostics, and source overlays.    |
+| `hoi4.probability_inspect`  | Locate weighted logic, candidates, required inputs, and supported analysis.             |
+| `hoi4.probability_evaluate` | Evaluate exact values, probabilities, timing, bounds, and unresolved inputs.            |
+| `hoi4.probability_sweep`    | Find sensitivity, breakpoints, cliffs, and rank reversals across declared ranges.       |
+| `hoi4.probability_simulate` | Run deterministic sampled analysis with confidence and convergence data.                |
+| `hoi4.probability_sequence` | Analyze declared recovery, caps, cooldowns, resets, timers, and terminal states.        |
+| `hoi4.probability_compare`  | Attribute AI-weight and MTTH changes between real or proposed source.                   |
+| `hoi4.probability_render`   | Render cached rankings, matrices, timing, sensitivity, sequence, and comparisons.       |
 
 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>`.
 
 ## Coexistence with agent workflows
 
-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.
+HOI4 Agent Tools provides HOI4 domain operations without replacing repository instructions such as `AGENTS.md`, skills, plans, or subagents. Its optional weighted-logic prompt helps an agent scope one probability analysis and then returns control to the normal 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. Event and technology tools analyze source without editing it; 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. Event, technology, and probability tools analyze source without editing it; only `hoi4.*_rewrite` calls edit mod source.
 
 ## Create or clean content
 
@@ -66,6 +74,7 @@ Ask your agent in normal task language. A typical workflow is inspect, render, r
 - 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).
 - Technology trees: "Explain everything this technology requires and unlocks," or "Compare this technology patch and render every affected folder and doctrine branch." See [Technology trees](docs/technology.md).
+- AI and MTTH: "Compare these focus weights across peace, defensive-war, and low-stability scenarios," or "Show when this MTTH event becomes likely and which unknown inputs control the result." See [AI and MTTH analysis](docs/probability.md).
 
 ## HTTP
 

package/dist/hoi4_agent_tools/core/clausewitz-evaluation.js

@@ -0,0 +1,90 @@
+import { compareCodeUnits } from './canonical.js';
+import { assignments, parseClausewitz, } from './source/index.js';
+const definitionCache = new WeakMap();
+function activeTextFiles(snapshot, prefix) {
+    return snapshot.files
+        .filter(({ relativePath, shadowedBy }) => shadowedBy === undefined &&
+        relativePath.replaceAll('\\', '/').toLowerCase().startsWith(prefix) &&
+        relativePath.toLowerCase().endsWith('.txt'))
+        .sort((left, right) => left.loadOrder - right.loadOrder || compareCodeUnits(left.displayPath, right.displayPath));
+}
+function scalarAssignments(block) {
+    return assignments(block).filter(({ value }) => value.type === 'scalar');
+}
+function flattenConstants(block, prefix, output, file, document) {
+    for (const assignment of assignments(block)) {
+        if (assignment.key.value === 'schema')
+            continue;
+        const id = prefix === '' ? assignment.key.value : `${prefix}.${assignment.key.value}`;
+        if (assignment.value.type === 'scalar') {
+            output.set(id, { id, value: assignment.value.value, node: assignment, file, document });
+        }
+        else {
+            flattenConstants(assignment.value, id, output, file, document);
+        }
+    }
+}
+/** Shared, source-linked definitions used by analysis domains. */
+export class ClausewitzEvaluationDefinitions {
+    scriptConstants = new Map();
+    mtthVariables = new Map();
+    scriptedTriggers = new Map();
+    localConstants = new Map();
+    static build(snapshot) {
+        const cached = definitionCache.get(snapshot);
+        if (cached !== undefined)
+            return cached;
+        const result = new ClausewitzEvaluationDefinitions();
+        for (const file of snapshot.files.filter(({ shadowedBy, relativePath }) => shadowedBy === undefined && relativePath.toLowerCase().endsWith('.txt'))) {
+            const document = parseClausewitz(file.bytes, file.displayPath);
+            const locals = new Map();
+            for (const assignment of scalarAssignments(document.root)) {
+                if (!assignment.key.value.startsWith('@') || assignment.value.type !== 'scalar')
+                    continue;
+                locals.set(assignment.key.value, {
+                    id: assignment.key.value,
+                    value: assignment.value.value,
+                    node: assignment,
+                    file,
+                    document,
+                });
+            }
+            if (locals.size > 0)
+                result.localConstants.set(file.displayPath, locals);
+        }
+        for (const file of activeTextFiles(snapshot, 'common/script_constants/')) {
+            const document = parseClausewitz(file.bytes, file.displayPath);
+            flattenConstants(document.root, '', result.scriptConstants, file, document);
+        }
+        for (const file of activeTextFiles(snapshot, 'common/mtth/')) {
+            const document = parseClausewitz(file.bytes, file.displayPath);
+            for (const assignment of assignments(document.root)) {
+                if (assignment.value.type !== 'block' || assignment.key.value.startsWith('@'))
+                    continue;
+                result.mtthVariables.set(assignment.key.value, {
+                    id: assignment.key.value,
+                    value: assignment.value,
+                    node: assignment,
+                    file,
+                    document,
+                });
+            }
+        }
+        for (const file of activeTextFiles(snapshot, 'common/scripted_triggers/')) {
+            const document = parseClausewitz(file.bytes, file.displayPath);
+            for (const assignment of assignments(document.root)) {
+                if (assignment.value.type !== 'block')
+                    continue;
+                result.scriptedTriggers.set(assignment.key.value, {
+                    id: assignment.key.value,
+                    value: assignment.value,
+                    node: assignment,
+                    file,
+                    document,
+                });
+            }
+        }
+        definitionCache.set(snapshot, result);
+        return result;
+    }
+}

package/dist/hoi4_agent_tools/core/engine.js

@@ -33,6 +33,11 @@ function defaultPatterns(workspace) {
             'common/characters/**/*.txt',
             'common/scripted_effects/**/*.txt',
             'common/scripted_triggers/**/*.txt',
+            'common/script_constants/**/*.txt',
+            'common/mtth/**/*.txt',
+            'common/ai_strategy/**/*.txt',
+            'common/ai_strategy_plans/**/*.txt',
+            'common/ai_focuses/**/*.txt',
             'common/on_actions/**/*.txt',
             'common/operations/**/*.txt',
             'common/raids/**/*.txt',

package/dist/hoi4_agent_tools/core/index.js

@@ -109,6 +109,14 @@ function possibleSymbolKinds(file, definitionFiles) {
             kinds.add('scripted_effect');
         if (sourcePath.startsWith('common/scripted_triggers/'))
             kinds.add('scripted_trigger');
+        if (sourcePath.startsWith('common/script_constants/'))
+            kinds.add('script_constant');
+        if (sourcePath.startsWith('common/mtth/'))
+            kinds.add('mtth_variable');
+        if (sourcePath.startsWith('common/ai_strategy/'))
+            kinds.add('ai_strategy');
+        if (sourcePath.startsWith('common/ai_strategy_plans/'))
+            kinds.add('ai_strategy_plan');
         if (sourcePath.startsWith('common/decisions/')) {
             kinds.add('decision');
             kinds.add('decision_category');
@@ -467,8 +475,23 @@ export class SymbolIndex {
         const sourcePath = file.relativePath.replaceAll('\\', '/').toLowerCase();
         for (const assignment of assignments(block)) {
             const key = assignment.key.value;
-            if (assignment.value.type !== 'block')
+            if (assignment.value.type !== 'block') {
+                if (sourcePath.startsWith('common/script_constants/') &&
+                    key !== 'schema' &&
+                    !ancestors.includes('schema')) {
+                    const id = [...ancestors, key].join('.');
+                    this.addSymbol({
+                        kind: 'script_constant',
+                        id,
+                        path: file.displayPath,
+                        rootKind: file.rootKind,
+                        loadOrder: file.loadOrder,
+                        location: nodeLocation(document, assignment, id),
+                        metadata: { value: assignment.value.value },
+                    });
+                }
                 continue;
+            }
             const child = assignment.value;
             const id = firstScalar(child, 'id')?.value;
             if (key === 'focus_tree' && id !== undefined) {
@@ -873,6 +896,39 @@ export class SymbolIndex {
                     metadata: {},
                 });
             }
+            else if (sourcePath.startsWith('common/mtth/') && ancestors.length === 0) {
+                this.addSymbol({
+                    kind: 'mtth_variable',
+                    id: key,
+                    path: file.displayPath,
+                    rootKind: file.rootKind,
+                    loadOrder: file.loadOrder,
+                    location: nodeLocation(document, assignment, key),
+                    metadata: {},
+                });
+            }
+            else if (sourcePath.startsWith('common/ai_strategy/') && ancestors.length === 0) {
+                this.addSymbol({
+                    kind: 'ai_strategy',
+                    id: key,
+                    path: file.displayPath,
+                    rootKind: file.rootKind,
+                    loadOrder: file.loadOrder,
+                    location: nodeLocation(document, assignment, key),
+                    metadata: {},
+                });
+            }
+            else if (sourcePath.startsWith('common/ai_strategy_plans/') && ancestors.length === 0) {
+                this.addSymbol({
+                    kind: 'ai_strategy_plan',
+                    id: key,
+                    path: file.displayPath,
+                    rootKind: file.rootKind,
+                    loadOrder: file.loadOrder,
+                    location: nodeLocation(document, assignment, key),
+                    metadata: {},
+                });
+            }
             else if (sourcePath.startsWith('common/decisions/') && ancestors.length === 0) {
                 this.addSymbol({
                     kind: 'decision_category',

package/dist/hoi4_agent_tools/core/source/ast-path.js

@@ -0,0 +1,41 @@
+const cachedPaths = new WeakMap();
+function indexBlock(block, path, output) {
+    output.set(block, path);
+    const occurrences = new Map();
+    for (const [index, entry] of block.entries.entries()) {
+        if (entry.type === 'assignment') {
+            const key = entry.key.value;
+            const occurrence = occurrences.get(key) ?? 0;
+            occurrences.set(key, occurrence + 1);
+            const entryPath = [...path, `${key}[${occurrence}]`];
+            output.set(entry, entryPath);
+            output.set(entry.key, [...entryPath, '$key']);
+            output.set(entry.value, entryPath);
+            if (entry.value.type === 'block')
+                indexBlock(entry.value, entryPath, output);
+            continue;
+        }
+        const entryPath = [...path, `#${entry.type}[${index}]`];
+        output.set(entry, entryPath);
+        if (entry.type === 'block')
+            indexBlock(entry, entryPath, output);
+    }
+}
+function pathsFor(document) {
+    const existing = cachedPaths.get(document);
+    if (existing !== undefined)
+        return existing;
+    const indexed = new WeakMap();
+    indexBlock(document.root, [], indexed);
+    cachedPaths.set(document, indexed);
+    return indexed;
+}
+/** Stable key-and-occurrence path for a node inside one parsed Clausewitz document. */
+export function astPathFor(document, node) {
+    const path = pathsFor(document).get(node);
+    return path === undefined ? undefined : [...path];
+}
+/** Test and diagnostic helper for callers that already hold a generic source entry. */
+export function sourceEntryAstPath(document, entry) {
+    return astPathFor(document, entry);
+}

package/dist/hoi4_agent_tools/core/source/index.js

@@ -1,4 +1,5 @@
 export * from './encoding.js';
+export * from './ast-path.js';
 export * from './lexer.js';
 export * from './limits.js';
 export * from './localisation.js';

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,17 @@ 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';
+    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 +1590,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 +1602,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

@@ -1,10 +1,13 @@
 import { ServiceError } from '../core/result.js';
-export const EVENT_GRAPH_MAX_NODES = 100_000;
+export const EVENT_GRAPH_MAX_NODES = 250_000;
 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;