hoi4-agent-tools 2.2.0 → 2.3.3

package/dist/hoi4_agent_tools/event/service.js

@@ -42,14 +42,16 @@ class BoundedEventFragmentCache {
         }
     }
 }
-function eventGraphCacheKey(workspaceId, projectHelpers) {
-    return `${workspaceId}\0${projectHelpers ? 'expanded' : 'structural'}`;
+function eventGraphCacheKey(workspaceId, projectHelpers, analysisMode = 'full') {
+    return `${workspaceId}\0${projectHelpers ? 'expanded' : 'structural'}\0${analysisMode}`;
 }
 const serviceState = new WeakMap();
 const EVENT_GRAPH_ARTIFACT_MAX_BYTES = 67_108_864;
 const EVENT_GRAPH_ARTIFACT_MAX_CHUNKS = 1_024;
 const EVENT_SCAN_FULL_GRAPH_RECORD_LIMIT = 100_000;
 const EVENT_SCAN_SUMMARY_SAMPLE_LIMIT = 100;
+const EVENT_FOCUSED_EVIDENCE_LIMIT = 2_000;
+const EVENT_FOCUSED_GRAPH_FILE_THRESHOLD = 1_000;
 const SHA256_PATTERN = /^[a-f0-9]{64}$/u;
 const graphHashCache = new WeakMap();
 function groupedCounts(values, key) {
@@ -116,7 +118,16 @@ function cachedEventGraphHash(graph, signal) {
     const cached = graphHashCache.get(graph);
     if (cached !== undefined)
         return cached;
-    const computed = eventGraphHash(graph, signal);
+    const computed = graph.analysisMode === 'focused'
+        ? hashCanonical({
+            schemaVersion: graph.schemaVersion,
+            parserVersion: graph.parserVersion,
+            workspaceIdentity: graph.workspaceIdentity,
+            revision: graph.revision,
+            statistics: graph.statistics,
+            sourceHashes: graph.sourceHashes,
+        })
+        : eventGraphHash(graph, signal);
     graphHashCache.set(graph, computed);
     return computed;
 }
@@ -135,6 +146,55 @@ function sharedState(engine) {
 function engineGeneration(engine, workspaceId) {
     return engine.generation(workspaceId);
 }
+function eventScanPatterns(workspace) {
+    const roots = workspace.registration.roots;
+    const under = (values, glob) => values.map((root) => `${root.replaceAll('\\', '/').replace(/\/$/u, '')}/${glob}`);
+    return [
+        'events/**/*.txt',
+        'history/countries/**/*.txt',
+        ...under(roots.states, '**/*.txt'),
+        'common/continuous_focus/**/*.txt',
+        'common/decisions/**/*.txt',
+        'common/ideas/**/*.txt',
+        'common/characters/**/*.txt',
+        'common/operations/**/*.txt',
+        'common/raids/**/*.txt',
+        'common/bop/**/*.txt',
+        'common/resistance_compliance_modifiers/**/*.txt',
+        'common/abilities/**/*.txt',
+        'common/on_actions/**/*.txt',
+        'common/special_projects/**/*.txt',
+        'common/scripted_effects/**/*.txt',
+        ...under(roots.focus, '**/*.txt'),
+        ...under(roots.scriptedGui, '**/*.txt'),
+        ...under(roots.localisation, 'english/**/*.{yml,yaml}'),
+        ...under(roots.localisation, '*.{yml,yaml}'),
+    ].sort(compareCodeUnits);
+}
+async function scanEventSources(engine, workspaceId, workspace, principal, signal) {
+    const patterns = eventScanPatterns(workspace);
+    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)]
+            : []),
+    ]);
+    const files = scans.flatMap(({ files }) => files.map((file) => ({ ...file })));
+    recomputeShadowing(files);
+    files.sort((left, right) => left.loadOrder - right.loadOrder || compareCodeUnits(left.displayPath, right.displayPath));
+    const index = engine.indexFiles(files);
+    return {
+        workspaceId,
+        revision: snapshotRevision(files),
+        files,
+        index,
+        complete: scans.every(({ complete }) => complete) && index.complete,
+        skippedSourceCount: index.skippedSourceCount,
+        skippedSources: index.skippedSources,
+        diagnostics: [...scans.flatMap(({ diagnostics }) => diagnostics), ...index.diagnostics],
+    };
+}
 function rememberGraph(state, workspaceId, graph) {
     const history = state.history.get(workspaceId) ?? new Map();
     history.delete(graph.revision);
@@ -163,6 +223,20 @@ function eventIssueDiagnostic(issue) {
         },
     };
 }
+function boundedEvidence(values, limit = EVENT_FOCUSED_EVIDENCE_LIMIT) {
+    if (values.length <= limit)
+        return { values: [...values] };
+    return {
+        values: values.slice(0, limit),
+        inventory: { count: values.length, retainedCount: limit, truncated: true },
+    };
+}
+function boundedUnresolved(graph, selectedNodeIds) {
+    const relevant = selectedNodeIds === undefined
+        ? graph.unresolved
+        : graph.unresolved.filter(({ id, ownerId }) => selectedNodeIds.has(id) || (ownerId !== undefined && selectedNodeIds.has(ownerId)));
+    return boundedEvidence(relevant);
+}
 export function eventDiagnostics(graph) {
     const existing = new Set(graph.diagnostics.map(({ code, location }) => `${code}:${location?.path ?? ''}:${location?.start.offset ?? -1}`));
     return [
@@ -618,37 +692,56 @@ export class EventChainViewer {
         const workspace = this.engine.resolver.get(workspaceId, options.principal);
         const generation = engineGeneration(this.engine, workspaceId);
         const projectHelpers = options.projectHelpers ?? true;
-        const cacheKey = eventGraphCacheKey(workspaceId, projectHelpers);
+        const analysisMode = options.analysisMode ?? 'full';
+        const cacheKey = eventGraphCacheKey(workspaceId, projectHelpers, analysisMode);
         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));
+        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 snapshot = options.refresh !== true && sibling?.generation === generation
             ? sibling.snapshot
-            : await this.engine.scan(workspaceId, {}, options.principal, options.signal);
+            : await scanEventSources(this.engine, workspaceId, workspace, 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
+            ? 'focused'
+            : 'full';
         const graph = buildEventGraph(snapshot, {
             ...(options.signal === undefined ? {} : { signal: options.signal }),
             cache: this.#state.fragments,
             workspaceIdentity: workspace.workspaceIdentity,
             projectHelpers,
+            analysisMode: buildAnalysisMode,
         });
         this.#state.current.set(cacheKey, { generation, snapshot, graph });
-        rememberGraph(this.#state, workspaceId, graph);
+        if (analysisMode === 'full')
+            rememberGraph(this.#state, workspaceId, graph);
         return graph;
     }
     async inspect(input) {
         input.signal?.throwIfAborted();
-        const graph = await this.scan(input.workspaceId, {
+        const scannedGraph = await this.scan(input.workspaceId, {
             refresh: input.refresh ?? input.mode === 'scan',
-            projectHelpers: input.mode !== 'scan' && input.mode !== 'roots',
+            // Focused routes traverse helper nodes directly and collapse only the
+            // selected path. Avoid materialising the full workspace projection first.
+            projectHelpers: input.mode !== 'scan' &&
+                input.mode !== 'roots' &&
+                input.mode !== 'trace' &&
+                input.mode !== 'explain_path',
+            ...(input.mode === 'trace' || input.mode === 'explain_path'
+                ? { analysisMode: 'focused' }
+                : {}),
             ...(input.principal === undefined ? {} : { principal: input.principal }),
             ...(input.signal === undefined ? {} : { signal: input.signal }),
         });
+        // Keep the service result's graph identity distinct from a prior scan while
+        // reusing its structural cache and avoiding a second large graph build.
+        const graph = input.mode === 'trace' || input.mode === 'explain_path' ? { ...scannedGraph } : scannedGraph;
         const maxDepth = input.maxDepth ?? 8;
         const maxNodes = input.maxNodes ?? 500;
         const maxEdges = input.maxEdges ?? 2_000;
@@ -671,28 +764,41 @@ export class EventChainViewer {
                 report = eventScanReport(graph);
                 break;
             case 'roots':
-                report = {
-                    graphRevision: graph.revision,
-                    sourceHashes: graph.sourceHashes,
-                    roots: discoverEventRoots(graph, input.signal),
-                    unresolved: graph.unresolved,
-                };
+                {
+                    const unresolved = boundedUnresolved(graph);
+                    report = {
+                        graphRevision: graph.revision,
+                        sourceHashes: graph.sourceHashes,
+                        roots: discoverEventRoots(graph, input.signal),
+                        unresolved: unresolved.values,
+                        ...(unresolved.inventory === undefined
+                            ? {}
+                            : { unresolvedInventory: unresolved.inventory }),
+                    };
+                }
                 break;
             case 'trace':
                 if (input.selector === undefined)
                     throw new ServiceError('EVENT_SELECTOR_REQUIRED', 'Trace requires a selector');
-                report = {
-                    graphRevision: graph.revision,
-                    sourceHashes: graph.sourceHashes,
-                    trace: traceSelectedEvents(graph, input.selector, {
+                {
+                    const trace = traceSelectedEvents(graph, input.selector, {
                         maxDepth,
                         maxNodes,
                         maxEdges,
                         direction: input.direction ?? 'both',
                         expandHelpers: input.expandHelpers ?? false,
-                    }, input.signal),
-                    unresolved: graph.unresolved,
-                };
+                    }, input.signal);
+                    const unresolved = boundedUnresolved(graph, new Set(trace.nodes.map(({ id }) => id)));
+                    report = {
+                        graphRevision: graph.revision,
+                        sourceHashes: graph.sourceHashes,
+                        trace,
+                        unresolved: unresolved.values,
+                        ...(unresolved.inventory === undefined
+                            ? {}
+                            : { unresolvedInventory: unresolved.inventory }),
+                    };
+                }
                 break;
             case 'explain_path':
                 if (input.from === undefined || input.to === undefined)
@@ -704,31 +810,54 @@ export class EventChainViewer {
                 };
                 break;
             case 'state_flow':
-                report = {
-                    graphRevision: graph.revision,
-                    sourceHashes: graph.sourceHashes,
-                    flow: inspectEventStateFlow(graph, input.selector, input.stateSubject, input.signal),
-                    issues: lintEventGraph(graph, input.selector, input.signal).filter(({ code }) => /(?:STATE|FLAG|VARIABLE|ARRAY|TARGET|SCOPE)/u.test(code)),
-                };
+                {
+                    const unresolved = boundedUnresolved(graph);
+                    const issues = boundedEvidence(lintEventGraph(graph, input.selector, input.signal).filter(({ code }) => /(?:STATE|FLAG|VARIABLE|ARRAY|TARGET|SCOPE)/u.test(code)));
+                    report = {
+                        graphRevision: graph.revision,
+                        sourceHashes: graph.sourceHashes,
+                        flow: inspectEventStateFlow(graph, input.selector, input.stateSubject, input.signal),
+                        issues: issues.values,
+                        unresolved: unresolved.values,
+                        ...(issues.inventory === undefined ? {} : { issueInventory: issues.inventory }),
+                        ...(unresolved.inventory === undefined
+                            ? {}
+                            : { unresolvedInventory: unresolved.inventory }),
+                    };
+                }
                 break;
             case 'lint':
-                report = {
-                    graphRevision: graph.revision,
-                    sourceHashes: graph.sourceHashes,
-                    issues: lintEventGraph(graph, input.selector, input.signal),
-                    complete: graph.complete,
-                    unresolved: graph.unresolved,
-                };
+                {
+                    const issues = boundedEvidence(lintEventGraph(graph, input.selector, input.signal));
+                    const unresolved = boundedUnresolved(graph);
+                    report = {
+                        graphRevision: graph.revision,
+                        sourceHashes: graph.sourceHashes,
+                        issues: issues.values,
+                        complete: graph.complete,
+                        unresolved: unresolved.values,
+                        ...(issues.inventory === undefined ? {} : { issueInventory: issues.inventory }),
+                        ...(unresolved.inventory === undefined
+                            ? {}
+                            : { unresolvedInventory: unresolved.inventory }),
+                    };
+                }
                 break;
             case 'impact':
                 if (input.impactSubject === undefined)
                     throw new ServiceError('EVENT_IMPACT_SUBJECT_REQUIRED', 'Impact analysis requires a subject');
-                report = {
-                    graphRevision: graph.revision,
-                    sourceHashes: graph.sourceHashes,
-                    impact: analyzeEventImpact(graph, input.impactSubject, input.signal),
-                    unresolved: graph.unresolved,
-                };
+                {
+                    const unresolved = boundedUnresolved(graph);
+                    report = {
+                        graphRevision: graph.revision,
+                        sourceHashes: graph.sourceHashes,
+                        impact: analyzeEventImpact(graph, input.impactSubject, input.signal),
+                        unresolved: unresolved.values,
+                        ...(unresolved.inventory === undefined
+                            ? {}
+                            : { unresolvedInventory: unresolved.inventory }),
+                    };
+                }
                 break;
         }
         const graphHash = cachedEventGraphHash(graph, input.signal);
@@ -742,7 +871,7 @@ export class EventChainViewer {
             : undefined;
         const artifactUnresolved = projectedScan
             ? graph.unresolved.slice(0, EVENT_SCAN_SUMMARY_SAMPLE_LIMIT)
-            : graph.unresolved;
+            : boundedUnresolved(graph).values;
         const reportJson = `${canonicalJson({
             schemaVersion: 'event-analysis.v1',
             graphSchemaVersion: graph.schemaVersion,
@@ -759,12 +888,12 @@ export class EventChainViewer {
             complete: graph.complete,
             filters: analysisFilters,
             unresolved: artifactUnresolved,
-            ...(projectedScan
+            ...(artifactUnresolved.length !== graph.unresolved.length
                 ? {
                     unresolvedInventory: {
                         count: graph.unresolved.length,
                         retainedCount: artifactUnresolved.length,
-                        truncated: artifactUnresolved.length !== graph.unresolved.length,
+                        truncated: true,
                     },
                 }
                 : {}),
@@ -950,7 +1079,15 @@ export class EventChainViewer {
                 includeHtml: input.includeHtml ?? false,
                 refresh: input.refresh ?? false,
             },
-            unresolved: graph.unresolved,
+            ...(() => {
+                const unresolved = boundedUnresolved(graph, new Set(render.selectedNodeIds));
+                return {
+                    unresolved: unresolved.values,
+                    ...(unresolved.inventory === undefined
+                        ? {}
+                        : { unresolvedInventory: unresolved.inventory }),
+                };
+            })(),
             resources: { ...resourceNames, artifacts: resourceLinks },
             overview: {
                 selectedNodeIds: render.selectedNodeIds,

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

@@ -5,8 +5,9 @@ import { registerGuiTools } from '../tools/gui.js';
 import { registerMapTools } from '../tools/map.js';
 import { registerEventTools } from '../tools/event.js';
 import { registerTechnologyTools } from '../tools/technology.js';
+import { registerProbabilityTools } from '../tools/probability.js';
 import { registerMcpResources } from '../resources/register.js';
-export const SERVER_INSTRUCTIONS = 'Use focus tools for focus trees, GUI tools for interfaces, and map tools for map data. Use hoi4.event_inspect, hoi4.event_render, and hoi4.event_compare for event chains. Use hoi4.tech_inspect, hoi4.tech_render, and hoi4.tech_compare for technology and doctrines. Event tools are read-only. Technology tools are read-only. Large evidence is linked as resources.';
+export const SERVER_INSTRUCTIONS = 'Use focus tools for focus trees, GUI tools for interfaces, and map tools for map data. Start unfamiliar event chains with hoi4.event_inspect. Event tools are read-only. Start technology and doctrine work with hoi4.tech_inspect. Technology tools are read-only. Start weighted AI, MTTH, random, and declared-pool analysis with hoi4.probability_inspect. Probability tools are read-only. Large evidence is linked as resources.';
 export function createMcpServer(engine, context = {}) {
     const server = new McpServer({
         name: PACKAGE_NAME,
@@ -21,6 +22,7 @@ export function createMcpServer(engine, context = {}) {
     registerMapTools(server, engine, context);
     registerEventTools(server, engine, context);
     registerTechnologyTools(server, engine, context);
+    registerProbabilityTools(server, engine, context);
     registerMcpResources(server, engine, context);
     return server;
 }

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

@@ -14,7 +14,6 @@ import { compactValidatedInputSchema } from '../server/context-schemas.js';
 import { nonNegativeIntegerSchema, sha256Schema } from '../server/output-schemas.js';
 import { progressReporter } from '../server/progress.js';
 import { errorResult, setInlineFilesScanned, strictOperationResultSchema, toolResult, } from '../server/result.js';
-import { computeFocusVisualRevisions } from './focus.js';
 const countryTagSchema = z
     .string()
     .regex(/^[A-Z0-9]{3}$/u)
@@ -43,12 +42,6 @@ const chaosxCountryAssetsOutput = strictOperationResultSchema(z
     artifactCount: nonNegativeIntegerSchema,
 })
     .strict());
-const visualFocusSelectorSchema = z
-    .object({
-    relativePath: z.string().min(1).max(1024),
-    treeId: z.string().min(1).max(256),
-})
-    .strict();
 const visualGuiSelectorSchema = z
     .object({
     windowName: z.string().min(1).max(256),
@@ -58,27 +51,20 @@ const visualGuiSelectorSchema = z
 const chaosxVisualRevisionInput = compactValidatedInputSchema(z
     .object({
     workspaceId: workspaceIdSchema,
-    focusTrees: z.array(visualFocusSelectorSchema).max(3).default([]),
-    guiWindows: z.array(visualGuiSelectorSchema).max(3).default([]),
-    countryTags: z.array(countryTagSchema).max(12).default([]),
-    eventId: z.number().int().min(0).max(999).optional(),
+    guiWindows: z.array(visualGuiSelectorSchema).min(1).max(3),
 })
-    .strict(), 'ChaosX-only selectors for fast visual cache revision checks');
+    .strict(), 'ChaosX-only scripted-GUI selectors for fast cache revision checks');
 const visualRevisionEntrySchema = z
     .object({
-    relativePath: z.string().min(1).max(1024).optional(),
-    treeId: z.string().min(1).max(256).optional(),
-    windowName: z.string().min(1).max(256).optional(),
-    guiId: z.string().min(1).max(256).optional(),
+    windowName: z.string().min(1).max(256),
+    guiId: z.string().min(1).max(256),
     revision: sha256Schema,
 })
     .strict();
 const chaosxVisualRevisionOutput = strictOperationResultSchema(z
     .object({
     workspaceRevision: sha256Schema,
-    focusRevisions: z.array(visualRevisionEntrySchema).max(3),
     guiRevisions: z.array(visualRevisionEntrySchema).max(3),
-    countryRevision: sha256Schema,
     dependencyFileCount: nonNegativeIntegerSchema,
 })
     .strict());
@@ -344,35 +330,12 @@ async function resolveGuiRevision(engine, context, studio, cache, workspaceId, s
         filesScanned: Object.keys(sourceHashes).sort(compareCodeUnits),
     };
 }
-function countryRevision(snapshot, selections, catalog) {
-    const sourceHashes = {};
-    for (const selection of selections) {
-        for (const sourcePath of [selection.discoverySourcePath, selection.spriteSourcePath]) {
-            if (sourcePath === undefined)
-                continue;
-            const source = snapshot.files.find(({ displayPath }) => displayPath === sourcePath);
-            if (source !== undefined)
-                sourceHashes[source.displayPath] = source.sha256;
-        }
-        for (const assetPath of [selection.flagPath, selection.leaderTexturePath]) {
-            if (assetPath === undefined)
-                continue;
-            const source = catalog.resolveFile(assetPath);
-            if (source !== undefined)
-                sourceHashes[source.displayPath] = source.sha256;
-        }
-    }
-    return {
-        revision: hashCanonical({ selections, sourceHashes }),
-        filesScanned: Object.keys(sourceHashes).sort(compareCodeUnits),
-    };
-}
 export function registerChaosxTools(server, engine, context) {
     const guiStudio = new ScriptedGuiStudio(engine);
     const guiRevisionCache = new Map();
     server.registerTool('chaosx.visual_revision', {
         title: 'Check ChaosX visual revisions',
-        description: 'Private ChaosX cache-coherency endpoint. Computes exact source revisions for event, focus, GUI, flag, and leader visuals without rendering PNG artifacts.',
+        description: 'Private ChaosX cache-coherency endpoint. Computes exact scripted-GUI source revisions without rendering PNG artifacts.',
         inputSchema: chaosxVisualRevisionInput,
         outputSchema: chaosxVisualRevisionOutput,
         annotations: readOnly,
@@ -380,41 +343,28 @@ export function registerChaosxTools(server, engine, context) {
         const workspaceId = engine.resolver.resolveWorkspaceId(input.workspaceId, context.principal);
         try {
             const progress = progressReporter(extra);
-            await progress.report(0, 4, 'Scanning ChaosX visual sources');
-            const snapshot = await engine.scan(workspaceId, {}, context.principal, progress.signal);
-            const focusRevisions = await computeFocusVisualRevisions(engine, context, workspaceId, snapshot, input.focusTrees, progress.signal);
-            await progress.report(1, 4, 'Checking ChaosX GUI sources');
+            await progress.report(0, 2, 'Checking ChaosX scripted-GUI sources');
             const resolvedGuiRevisions = [];
             for (const selector of input.guiWindows)
                 resolvedGuiRevisions.push(await resolveGuiRevision(engine, context, guiStudio, guiRevisionCache, workspaceId, selector, progress.signal));
+            const filesScanned = new Set(resolvedGuiRevisions.flatMap(({ filesScanned }) => filesScanned));
             const guiRevisions = resolvedGuiRevisions.map(({ windowName, guiId, revision }) => ({
                 windowName,
                 guiId,
                 revision,
             }));
-            await progress.report(2, 4, 'Checking ChaosX country artwork');
-            const tags = [...new Set(input.countryTags)];
-            const { selections, catalog } = await selectCountryAssets(engine, snapshot, workspaceId, tags, input.eventId, context, progress.signal);
-            const countries = countryRevision(snapshot, selections, catalog);
-            const filesScanned = new Set([
-                ...focusRevisions.flatMap(({ filesScanned }) => filesScanned),
-                ...resolvedGuiRevisions.flatMap(({ filesScanned }) => filesScanned),
-                ...countries.filesScanned,
-            ]);
+            const workspaceRevision = hashCanonical(resolvedGuiRevisions.map(({ windowName, workspaceRevision: revision }) => ({
+                windowName,
+                revision,
+            })));
             const result = emptyServiceResult(workspaceId, {
-                workspaceRevision: snapshot.revision,
-                focusRevisions: focusRevisions.map(({ relativePath, treeId, revision }) => ({
-                    relativePath,
-                    treeId,
-                    revision,
-                })),
+                workspaceRevision,
                 guiRevisions,
-                countryRevision: countries.revision,
                 dependencyFileCount: filesScanned.size,
             });
             result.code = 'CHAOSX_VISUAL_REVISION_CHECKED';
             setInlineFilesScanned(result, [...filesScanned].sort(compareCodeUnits));
-            await progress.report(4, 4, 'ChaosX visual revisions complete');
+            await progress.report(2, 2, 'ChaosX scripted-GUI revisions complete');
             return toolResult(result);
         }
         catch (error) {