hoi4-agent-tools 2.3.3 → 2.3.4

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # 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.

package/dist/hoi4_agent_tools/event/graph.js

@@ -1571,6 +1571,20 @@ export function buildEventGraph(snapshot, options = {}) {
     graph.stateAccesses = stableUnique(graph.stateAccesses);
     graph.unresolved = stableUnique(graph.unresolved);
     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);

package/dist/hoi4_agent_tools/event/service.js

@@ -45,6 +45,9 @@ class BoundedEventFragmentCache {
 function eventGraphCacheKey(workspaceId, projectHelpers, analysisMode = 'full') {
     return `${workspaceId}\0${projectHelpers ? 'expanded' : 'structural'}\0${analysisMode}`;
 }
+function isGameBackedWorkspace(workspace) {
+    return workspace.roots.some(({ kind }) => kind === 'game');
+}
 const serviceState = new WeakMap();
 const EVENT_GRAPH_ARTIFACT_MAX_BYTES = 67_108_864;
 const EVENT_GRAPH_ARTIFACT_MAX_CHUNKS = 1_024;
@@ -77,6 +80,7 @@ export function eventScanReport(graph, fullGraphRecordLimit = EVENT_SCAN_FULL_GR
         graphSummary: {
             schemaVersion: graph.schemaVersion,
             parserVersion: graph.parserVersion,
+            analysisMode: graph.analysisMode ?? 'full',
             workspaceId: graph.workspaceId,
             workspaceIdentity: graph.workspaceIdentity,
             revision: graph.revision,
@@ -122,6 +126,7 @@ function cachedEventGraphHash(graph, signal) {
         ? hashCanonical({
             schemaVersion: graph.schemaVersion,
             parserVersion: graph.parserVersion,
+            analysisMode: graph.analysisMode ?? 'full',
             workspaceIdentity: graph.workspaceIdentity,
             revision: graph.revision,
             statistics: graph.statistics,
@@ -146,9 +151,12 @@ function sharedState(engine) {
 function engineGeneration(engine, workspaceId) {
     return engine.generation(workspaceId);
 }
-function eventScanPatterns(workspace) {
+function eventScanPatterns(workspace, focused = false) {
     const roots = workspace.registration.roots;
     const under = (values, glob) => values.map((root) => `${root.replaceAll('\\', '/').replace(/\/$/u, '')}/${glob}`);
+    if (focused) {
+        return ['events/**/*.txt', 'common/on_actions/**/*.txt'].sort(compareCodeUnits);
+    }
     return [
         'events/**/*.txt',
         'history/countries/**/*.txt',
@@ -171,13 +179,16 @@ function eventScanPatterns(workspace) {
         ...under(roots.localisation, '*.{yml,yaml}'),
     ].sort(compareCodeUnits);
 }
-async function scanEventSources(engine, workspaceId, workspace, principal, signal) {
-    const patterns = eventScanPatterns(workspace);
+async function scanEventSources(engine, workspaceId, workspace, focused = false, principal, signal) {
+    const patterns = eventScanPatterns(workspace, focused);
+    const gamePatterns = eventScanPatterns(workspace, focused);
     const sourceKinds = ['mod', 'dependency', 'fixture'];
     const scans = await Promise.all([
         engine.scan(workspaceId, { patterns, rootKinds: sourceKinds }, principal, signal),
         ...(workspace.roots.some(({ kind }) => kind === 'game')
-            ? [engine.scan(workspaceId, { patterns, rootKinds: ['game'] }, principal, signal)]
+            ? [
+                engine.scan(workspaceId, { patterns: gamePatterns, rootKinds: ['game'] }, principal, signal),
+            ]
             : []),
     ]);
     const files = scans.flatMap(({ files }) => files.map((file) => ({ ...file })));
@@ -691,26 +702,32 @@ export class EventChainViewer {
         // principal bypass the resolver check for a later caller.
         const workspace = this.engine.resolver.get(workspaceId, options.principal);
         const generation = engineGeneration(this.engine, workspaceId);
-        const projectHelpers = options.projectHelpers ?? true;
-        const analysisMode = options.analysisMode ?? 'full';
-        const cacheKey = eventGraphCacheKey(workspaceId, projectHelpers, analysisMode);
+        const requestedProjectHelpers = options.projectHelpers ?? true;
+        const requestedAnalysisMode = options.analysisMode ?? 'full';
+        const autoFocused = isGameBackedWorkspace(workspace) && requestedAnalysisMode === 'full';
+        const cacheAnalysisMode = autoFocused ? 'focused' : requestedAnalysisMode;
+        const cacheProjectHelpers = cacheAnalysisMode === 'focused' ? false : requestedProjectHelpers;
+        const cacheKey = eventGraphCacheKey(workspaceId, cacheProjectHelpers, cacheAnalysisMode);
         const cached = this.#state.current.get(cacheKey);
         if (options.refresh !== true && cached?.generation === generation) {
             return cached.graph;
         }
-        const sibling = this.#state.current.get(eventGraphCacheKey(workspaceId, !projectHelpers, analysisMode)) ??
-            this.#state.current.get(eventGraphCacheKey(workspaceId, !projectHelpers)) ??
-            this.#state.current.get(eventGraphCacheKey(workspaceId, projectHelpers));
+        const sibling = this.#state.current.get(eventGraphCacheKey(workspaceId, !cacheProjectHelpers, cacheAnalysisMode)) ??
+            this.#state.current.get(eventGraphCacheKey(workspaceId, requestedProjectHelpers, requestedAnalysisMode)) ??
+            this.#state.current.get(eventGraphCacheKey(workspaceId, !requestedProjectHelpers)) ??
+            this.#state.current.get(eventGraphCacheKey(workspaceId, requestedProjectHelpers));
+        const scanFocused = autoFocused || requestedAnalysisMode === 'focused';
         const snapshot = options.refresh !== true && sibling?.generation === generation
             ? sibling.snapshot
-            : await scanEventSources(this.engine, workspaceId, workspace, options.principal, options.signal);
+            : await scanEventSources(this.engine, workspaceId, workspace, scanFocused, options.principal, options.signal);
         options.signal?.throwIfAborted();
         if (cached?.snapshot.revision === snapshot.revision && cached.generation === generation) {
             return cached.graph;
         }
-        const buildAnalysisMode = analysisMode === 'focused' && snapshot.files.length > EVENT_FOCUSED_GRAPH_FILE_THRESHOLD
+        const buildAnalysisMode = autoFocused || snapshot.files.length > EVENT_FOCUSED_GRAPH_FILE_THRESHOLD
             ? 'focused'
             : 'full';
+        const projectHelpers = buildAnalysisMode === 'focused' ? false : requestedProjectHelpers;
         const graph = buildEventGraph(snapshot, {
             ...(options.signal === undefined ? {} : { signal: options.signal }),
             cache: this.#state.fragments,
@@ -719,7 +736,7 @@ export class EventChainViewer {
             analysisMode: buildAnalysisMode,
         });
         this.#state.current.set(cacheKey, { generation, snapshot, graph });
-        if (analysisMode === 'full')
+        if (buildAnalysisMode === 'full')
             rememberGraph(this.#state, workspaceId, graph);
         return graph;
     }

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

@@ -122,6 +122,7 @@ const renderHashSchema = z
 const eventInspectOutputSchema = strictOperationResultSchema(z
     .object({
     mode: eventInspectModeSchema,
+    analysisMode: z.enum(['full', 'focused']),
     revision: sha256Schema,
     graphHash: sha256Schema,
     counts: eventGraphCountsSchema,
@@ -131,6 +132,7 @@ const eventInspectOutputSchema = strictOperationResultSchema(z
 const eventRenderOutputSchema = strictOperationResultSchema(z
     .object({
     view: eventRenderViewSchema,
+    analysisMode: z.enum(['full', 'focused']),
     revision: sha256Schema,
     graphHash: sha256Schema,
     layoutHash: sha256Schema,
@@ -223,15 +225,18 @@ function graphCounts(graph, artifacts) {
 }
 function graphValidation(graph) {
     const counts = graphCounts(graph, 0);
+    const focused = graph.analysisMode === 'focused';
     return {
         passed: graph.complete && counts.blockingDiagnostics === 0,
         checks: [
             {
                 id: 'event-analysis',
                 passed: graph.complete && counts.blockingDiagnostics === 0,
-                message: graph.complete
-                    ? `${counts.blockingDiagnostics} blocking event-chain diagnostics; full evidence is linked`
-                    : `${graph.skippedSourceCount} event-analysis source(s) were skipped; full evidence is linked`,
+                message: focused
+                    ? 'Large workspace analysis deferred workspace-wide helper projections and lifecycle passes; direct evidence is linked'
+                    : graph.complete
+                        ? `${counts.blockingDiagnostics} blocking event-chain diagnostics; full evidence is linked`
+                        : `${graph.skippedSourceCount} event-analysis source(s) were skipped; full evidence is linked`,
             },
         ],
     };
@@ -314,6 +319,7 @@ export function registerEventTools(server, engine, context) {
             await progress.report(2, 3, 'Linking complete event analysis');
             const result = emptyServiceResult(workspaceId, {
                 mode: inspected.mode,
+                analysisMode: inspected.graph.analysisMode ?? 'full',
                 revision: inspected.graph.revision,
                 graphHash: inspected.graphHash,
                 counts: graphCounts(inspected.graph, inspected.artifacts.length),
@@ -352,6 +358,7 @@ export function registerEventTools(server, engine, context) {
             await progress.report(2, 3, 'Linking complete event renders');
             const result = emptyServiceResult(workspaceId, {
                 view: rendered.render.view,
+                analysisMode: rendered.graph.analysisMode ?? 'full',
                 revision: rendered.graph.revision,
                 graphHash: rendered.graphHash,
                 layoutHash: rendered.render.layout.layoutHash,

package/dist/hoi4_agent_tools/version.js

@@ -1,6 +1,6 @@
 import { LATEST_PROTOCOL_VERSION } from '@modelcontextprotocol/sdk/types.js';
 export const PACKAGE_NAME = 'hoi4-agent-tools';
-export const PACKAGE_VERSION = '2.3.3';
+export const PACKAGE_VERSION = '2.3.4';
 export const MCP_PROTOCOL_VERSION = LATEST_PROTOCOL_VERSION;
 export const CONFIG_VERSION = 1;
 export const TRANSACTION_VERSION = 1;

package/docs/events.md

@@ -16,9 +16,9 @@ Use the three event tools directly from the target mod.
 - `lint`: find missing targets, unreachable events, suspicious cycles, conflicting definitions, invalid timing, and unresolved dynamic calls.
 - `impact`: identify callers, descendants, state dependencies, and files affected by a proposed event change.
 
-Use narrow identifiers, direction, and depth limits when the task concerns one chain. Broad scans build the structural event graph without expanding every scripted helper into duplicate paths. Focused trace and path calls traverse helper nodes and collapse only the selected bounded route, while state, impact, and render calls expand helper relationships when their workspace-wide evidence requires it.
+Use narrow identifiers, direction, and depth limits when the task concerns one chain. Broad scans build the structural event graph without expanding every scripted helper into duplicate paths. Game-backed or other large workspaces automatically use a focused source profile containing event definitions and on-actions, then defer workspace-wide helper projections and lifecycle passes. The result is marked partial and records that boundary in the linked evidence instead of waiting until the MCP transport times out. Focused trace and path calls collapse only the selected bounded route.
 
-The compact response summarizes the result. Small scan resources contain the complete graph; very large scan resources contain exact totals, grouped inventories, representative diagnostics, and the revision needed for focused follow-up queries. The viewer retains the complete in-memory graph for those follow-up queries, and the event issue ceiling is high enough for installed-game-scale diagnostic inventories. This keeps an agent's prompt and artifact storage bounded without reducing the results of those focused queries.
+The compact response summarizes the result. Small scan resources contain the complete graph; large scan resources contain exact totals, grouped inventories, representative diagnostics, and the revision needed for focused follow-up queries. Large focused scans keep direct event and on-action evidence, call sites, state accesses, and source locations while leaving helper expansion and workspace-wide lifecycle analysis explicit as deferred boundaries. This keeps an agent's prompt and artifact storage bounded without allowing a broad scan to exhaust the MCP process.
 
 Selectors use one of these forms:
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hoi4-agent-tools",
   "mcpName": "io.github.klimPaskov/hoi4-agent-tools",
-  "version": "2.3.3",
+  "version": "2.3.4",
   "description": "Analyze HOI4 events, tech trees, AI weights, and MTTH; build focus trees, GUIs, and maps.",
   "type": "module",
   "license": "Apache-2.0",

package/schemas/configuration.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.3/schemas/configuration.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.4/schemas/configuration.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/continuous-focus-palette.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.3/schemas/continuous-focus-palette.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.4/schemas/continuous-focus-palette.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/custom-weighted-pool.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.3/schemas/custom-weighted-pool.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.4/schemas/custom-weighted-pool.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/event-feature-manifest.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.3/schemas/event-feature-manifest.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.4/schemas/event-feature-manifest.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/focus-plan.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.3/schemas/focus-plan.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.4/schemas/focus-plan.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/focus-planning-sidecar.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.3/schemas/focus-planning-sidecar.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.4/schemas/focus-planning-sidecar.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/gui-animation-source.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.3/schemas/gui-animation-source.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.4/schemas/gui-animation-source.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/gui-helper.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.3/schemas/gui-helper.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.4/schemas/gui-helper.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/gui-scenario.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.3/schemas/gui-scenario.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.4/schemas/gui-scenario.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/map-operation.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.3/schemas/map-operation.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.4/schemas/map-operation.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "oneOf": [
     {

package/schemas/operation-result.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.3/schemas/operation-result.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.4/schemas/operation-result.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/probability-analysis-result.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.3/schemas/probability-analysis-result.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.4/schemas/probability-analysis-result.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/probability-compare-input.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.3/schemas/probability-compare-input.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.4/schemas/probability-compare-input.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/probability-evaluate-input.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.3/schemas/probability-evaluate-input.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.4/schemas/probability-evaluate-input.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/probability-inspect-input.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.3/schemas/probability-inspect-input.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.4/schemas/probability-inspect-input.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/probability-render-input.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.3/schemas/probability-render-input.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.4/schemas/probability-render-input.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/probability-scenario-set.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.3/schemas/probability-scenario-set.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.4/schemas/probability-scenario-set.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/probability-sequence-input.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.3/schemas/probability-sequence-input.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.4/schemas/probability-sequence-input.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/probability-simulate-input.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.3/schemas/probability-simulate-input.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.4/schemas/probability-simulate-input.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/probability-sweep-input.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.3/schemas/probability-sweep-input.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.3.4/schemas/probability-sweep-input.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.klimPaskov/hoi4-agent-tools",
   "title": "HOI4 Agent Tools",
   "description": "Analyze HOI4 events, tech trees, AI weights, and MTTH; build focus trees, GUIs, and maps.",
-  "version": "2.3.3",
+  "version": "2.3.4",
   "repository": {
     "url": "https://github.com/klimPaskov/hoi4-agent-tools",
     "source": "github"
@@ -13,7 +13,7 @@
     {
       "registryType": "npm",
       "identifier": "hoi4-agent-tools",
-      "version": "2.3.3",
+      "version": "2.3.4",
       "transport": {
         "type": "stdio"
       }