hoi4-agent-tools 3.3.0 → 3.4.1

package/dist/hoi4_agent_tools/map/render.js

@@ -357,7 +357,50 @@ export async function renderMap(index, options = {}) {
         throw new ServiceError('MAP_RENDER_SCALE_INVALID', 'Map render scale must be an integer from 1 through 16');
     const budget = options.budget ?? new RenderBudget();
     assertRenderDimensions(raster.width, raster.height, 'map RGBA source plane');
-    const outputDimensions = budget.reserve(raster.width * resolved.scale, raster.height * resolved.scale, 'map PNG output');
+    let tile = options.tile;
+    if (options.area !== undefined) {
+        if (tile !== undefined)
+            throw new ServiceError('MAP_RENDER_AREA_CONFLICT', 'Choose a map tile or entity area');
+        const ids = new Set(options.area.provinceIds ?? []);
+        for (const stateId of options.area.stateIds ?? []) {
+            const state = index.statesById.get(stateId);
+            if (state === undefined)
+                throw new ServiceError('MAP_AREA_STATE_MISSING', 'Map area state ID is missing', {
+                    stateId,
+                });
+            for (const id of state.provinces)
+                ids.add(id);
+        }
+        for (const regionId of options.area.regionIds ?? []) {
+            const region = index.regionsById.get(regionId);
+            if (region === undefined)
+                throw new ServiceError('MAP_AREA_REGION_MISSING', 'Map area region ID is missing', {
+                    regionId,
+                });
+            for (const id of region.provinces)
+                ids.add(id);
+        }
+        if (ids.size === 0)
+            throw new ServiceError('MAP_AREA_EMPTY', 'Map area has no provinces');
+        const geometry = [...ids].map((id) => {
+            const province = raster.geometry.get(id);
+            if (province === undefined)
+                throw new ServiceError('MAP_AREA_PROVINCE_MISSING', 'Map area province ID has no raster geometry', { provinceId: id });
+            return province;
+        });
+        const padding = options.area.padding ?? 32;
+        const x = Math.max(0, Math.min(...geometry.map(({ minX }) => minX)) - padding);
+        const y = Math.max(0, Math.min(...geometry.map(({ minY }) => minY)) - padding);
+        const right = Math.min(raster.width, Math.max(...geometry.map(({ maxX }) => maxX)) + padding + 1);
+        const bottom = Math.min(raster.height, Math.max(...geometry.map(({ maxY }) => maxY)) + padding + 1);
+        tile = { x, y, width: right - x, height: bottom - y };
+        if (tile.width > 2_048 || tile.height > 2_048)
+            throw new ServiceError('MAP_AREA_TOO_LARGE', 'Map area exceeds the tile limit; select fewer entities', { tile });
+    }
+    if (tile !== undefined &&
+        (tile.x + tile.width > raster.width || tile.y + tile.height > raster.height))
+        throw new ServiceError('MAP_TILE_OUT_OF_BOUNDS', 'Map tile extends beyond the province raster', { tile, rasterWidth: raster.width, rasterHeight: raster.height });
+    const outputDimensions = budget.reserve((tile?.width ?? raster.width) * resolved.scale, (tile?.height ?? raster.height) * resolved.scale, 'map PNG output');
     const raw = Buffer.alloc(raster.width * raster.height * 4);
     for (let offset = 0; offset < raster.provinceIds.length; offset += 1) {
         if (offset % Math.max(raster.width * 32, 1) === 0)
@@ -371,6 +414,32 @@ export async function renderMap(index, options = {}) {
     }
     await applyOverlays(index, raw, new Set(resolved.overlays), options.signal);
     options.signal?.throwIfAborted();
+    if (tile !== undefined) {
+        const tileRaw = Buffer.alloc(tile.width * tile.height * 4);
+        const provinceIds = new Set();
+        for (let row = 0; row < tile.height; row += 1) {
+            if (row % 32 === 0)
+                await renderCheckpoint(options.signal);
+            raw.copy(tileRaw, row * tile.width * 4, ((tile.y + row) * raster.width + tile.x) * 4, ((tile.y + row) * raster.width + tile.x + tile.width) * 4);
+            for (let column = 0; column < tile.width; column += 1) {
+                const id = raster.provinceIds[(tile.y + row) * raster.width + tile.x + column];
+                if (id !== undefined && id >= 0)
+                    provinceIds.add(id);
+            }
+        }
+        const png = await encodePng(tileRaw, tile.width, tile.height, resolved.scale);
+        const json = `${canonicalJson({ schemaVersion: 'map-tile.v1', layer: resolved.layer, overlays: resolved.overlays, scale: resolved.scale, tile, raster: { width: raster.width, height: raster.height }, provinceIds: [...provinceIds].sort((left, right) => left - right) })}\n`;
+        const html = diffHtmlDocument(`HOI4 map tile - ${resolved.layer}`, png, json);
+        return {
+            width: outputDimensions.width,
+            height: outputDimensions.height,
+            tile,
+            png,
+            json,
+            html,
+            hashes: { png: sha256Bytes(png), json: sha256Bytes(json), html: sha256Bytes(html) },
+        };
+    }
     const png = await encodePng(raw, raster.width, raster.height, resolved.scale);
     options.signal?.throwIfAborted();
     const json = `${canonicalJson(await renderMetadata(index, resolved, options.signal))}\n`;

package/dist/hoi4_agent_tools/map/service.js

@@ -481,7 +481,7 @@ export class AgentNudger {
         this.scanner = this.engine.scanner;
         this.transactions = this.engine.transactions;
     }
-    async scan(workspaceId, principal, signal) {
+    async scan(workspaceId, principal, signal, includeExternalScriptReferences = false) {
         signal?.throwIfAborted();
         const workspace = this.resolver.get(workspaceId, principal);
         const sourceRoots = {
@@ -493,8 +493,27 @@ export class AgentNudger {
         const bitmapPatterns = provinceBitmapPatterns(selectorSnapshot.files, sourceRoots.map);
         const contentSnapshot = await this.engine.scan(workspaceId, { patterns: [...sourceTextPatterns(sourceRoots), ...bitmapPatterns] }, principal, signal);
         const locatorSnapshot = await this.engine.scan(workspaceId, { patterns: ['**/*.asset'], rootKinds: ['mod', 'fixture'] }, principal, signal);
+        const externalScriptSnapshot = includeExternalScriptReferences
+            ? await this.engine.scan(workspaceId, {
+                patterns: [
+                    'events/**/*.txt',
+                    'common/national_focus/**/*.txt',
+                    'common/decisions/**/*.txt',
+                    'common/scripted_effects/**/*.txt',
+                    'common/scripted_triggers/**/*.txt',
+                    'common/on_actions/**/*.txt',
+                    'common/ideas/**/*.txt',
+                    'common/characters/**/*.txt',
+                    'history/countries/**/*.txt',
+                ],
+            }, principal, signal)
+            : undefined;
         signal?.throwIfAborted();
-        const files = [...contentSnapshot.files, ...locatorSnapshot.files].sort((left, right) => left.loadOrder - right.loadOrder || compareCodeUnits(left.displayPath, right.displayPath));
+        const files = [
+            ...contentSnapshot.files,
+            ...locatorSnapshot.files,
+            ...(externalScriptSnapshot?.files ?? []),
+        ].sort((left, right) => left.loadOrder - right.loadOrder || compareCodeUnits(left.displayPath, right.displayPath));
         const revision = hashCanonical(files.map(({ displayPath, loadOrder, sha256 }) => ({ displayPath, loadOrder, sha256 })));
         return {
             workspaceId,
@@ -512,7 +531,7 @@ export class AgentNudger {
     }
     async prepareOperations(workspaceId, operations, principal, signal) {
         signal?.throwIfAborted();
-        const snapshot = await this.scan(workspaceId, principal, signal);
+        const snapshot = await this.scan(workspaceId, principal, signal, operations.some(({ kind }) => kind === 'renumber_map_entity'));
         const plan = await planMapOperationsAsync(snapshot.index, operations, signal);
         const baselineValidation = await validateMapAsync(snapshot.index, signal === undefined ? {} : { signal });
         const rawValidation = await validateMapAsync(plan.finalIndex, {
@@ -614,6 +633,9 @@ export class AgentNudger {
         const bundle = mapBundleWithSourceHashes(rawBundle, completeSourceHashes);
         const workspace = this.resolver.get(workspaceId, options.principal);
         const layer = options.layer ?? 'province';
+        const tileSuffix = options.tile === undefined && options.area === undefined
+            ? ''
+            : `-tile-${hashCanonical({ tile: bundle.tile, area: options.area, overlays: [...new Set(options.overlays ?? [])].sort(), scale: options.scale ?? 1 }).slice(0, 12)}`;
         const provenance = {
             kind: 'map-render',
             toolVersion: PACKAGE_VERSION,
@@ -624,24 +646,26 @@ export class AgentNudger {
                 layer,
                 overlays: [...new Set(options.overlays ?? [])].sort(),
                 scale: options.scale ?? 1,
+                ...(bundle.tile === undefined ? {} : { tile: bundle.tile }),
+                ...(options.area === undefined ? {} : { area: options.area }),
             },
             metadata: { sourceHashInventory: sourceEvidence.inventory },
         };
         const writes = [
             {
-                name: `map-${layer}.png`,
+                name: `map-${layer}${tileSuffix}.png`,
                 mimeType: 'image/png',
                 content: bundle.png,
                 provenance,
             },
             {
-                name: `map-${layer}.json`,
+                name: `map-${layer}${tileSuffix}.json`,
                 mimeType: 'application/json',
                 content: bundle.json,
                 provenance,
             },
             {
-                name: `map-${layer}.html`,
+                name: `map-${layer}${tileSuffix}.html`,
                 mimeType: 'text/html',
                 content: bundle.html,
                 provenance,

package/dist/hoi4_agent_tools/map/tool-operations.js

@@ -1,7 +1,7 @@
 import { boundedSourceHashEvidence, publicArtifactLink, } from '../core/artifacts.js';
 import { canonicalJson, hashCanonical } from '../core/canonical.js';
 import { autonomousResultArtifacts, } from '../core/transaction-execution.js';
-import { emptyServiceResult } from '../core/result.js';
+import { emptyServiceResult, ServiceError } from '../core/result.js';
 import { setInlineFilesScanned } from '../core/operation-result.js';
 import { PACKAGE_VERSION } from '../version.js';
 import { allocateMapIdentifiersAsync, } from './operations.js';
@@ -299,6 +299,69 @@ export function completeMapRewrite(workspaceId, execution, recipe) {
 }
 export async function inspectMap(engine, nudger, input, context) {
     await context.progress(0, 3, 'Inspecting and validating the map');
+    if (input.lookupOnly) {
+        if (input.allocationRequests.length > 0)
+            throw new ServiceError('MAP_LOOKUP_ALLOCATION_UNSUPPORTED', 'Use full map inspection for identifier allocation previews');
+        const snapshot = await nudger.scan(context.workspaceId, context.principal, context.signal);
+        const catalog = input.query === undefined ? undefined : buildMapCatalog(snapshot.index);
+        const queryMatches = catalog === undefined ? [] : searchMapCatalog(catalog, input.query, input.queryLimit);
+        const coordinateMatches = input.coordinates.map((coordinate) => lookupMapCoordinate(snapshot.index, coordinate));
+        const selected = selectedMapEntities(snapshot, input.provinceIds, input.stateIds, input.regionIds);
+        const workspace = engine.resolver.get(context.workspaceId, context.principal);
+        const sourceEvidence = mapArtifactSourceEvidence(snapshot.files);
+        const selectorHash = hashCanonical({
+            provinceIds: input.provinceIds,
+            stateIds: input.stateIds,
+            regionIds: input.regionIds,
+            query: input.query,
+            coordinates: input.coordinates,
+        }).slice(0, 16);
+        const artifact = await engine.artifacts.putChunked(workspace, `map-lookup.${snapshot.revision.slice(0, 16)}.${selectorHash}.json`, 'application/json', `${canonicalJson({ schemaVersion: 1, revision: snapshot.revision, lookupOnly: true, queryMatches, coordinateMatches, selected, sourceHashes: sourceEvidence.complete })}\n`, {
+            kind: 'map-lookup',
+            toolVersion: PACKAGE_VERSION,
+            schemaVersion: 'map-lookup.v1',
+            sourceHashes: sourceEvidence.bounded.sourceHashes,
+            metadata: { sourceHashInventory: sourceEvidence.bounded.inventory },
+        }, 'Bounded map coordinate, catalog, and entity lookup without full validation or overview rendering', context.signal);
+        const result = emptyServiceResult(context.workspaceId, {
+            revision: snapshot.revision,
+            sharedRevision: snapshot.revision,
+            width: snapshot.index.raster?.width ?? null,
+            height: snapshot.index.raster?.height ?? null,
+            definitions: snapshot.index.definitions.length,
+            states: snapshot.index.states.length,
+            regions: snapshot.index.regions.length,
+            ports: snapshot.index.ports.length,
+            inspectedProvinceCount: selected.provinces.length,
+            inspectedStateCount: selected.states.length,
+            inspectedRegionCount: selected.regions.length,
+            allocationCount: 0,
+            queryMatchCount: queryMatches.length,
+            coordinateMatchCount: coordinateMatches.length,
+            overviewRendered: false,
+            provinceGeometryCount: 0,
+            provinceGeometryPixelCount: 0,
+            provinceGeometryRowRunCount: 0,
+            unknownProvinceIds: [],
+            missingGeometryProvinceIds: [],
+            lookupOnly: true,
+        });
+        result.code = 'MAP_LOOKUP_COMPLETED';
+        result.validation = {
+            passed: true,
+            checks: [
+                {
+                    id: 'lookup-only',
+                    passed: true,
+                    message: 'Lookup completed; full map validation was not requested',
+                },
+            ],
+        };
+        setInlineFilesScanned(result, snapshot.files.map(({ displayPath }) => displayPath));
+        result.artifacts = [publicArtifactLink(artifact)];
+        await context.progress(3, 3, 'Map lookup complete');
+        return result;
+    }
     const { snapshot, validation } = await nudger.validate(context.workspaceId, context.principal, context.signal);
     const sharedRevision = snapshot.revision;
     const catalog = buildMapCatalog(snapshot.index);
@@ -474,6 +537,8 @@ export async function renderMapView(nudger, input, context) {
         ...(input.layer === undefined ? {} : { layer: input.layer }),
         ...(input.overlays === undefined ? {} : { overlays: input.overlays }),
         ...(input.scale === undefined ? {} : { scale: input.scale }),
+        ...(input.tile === undefined ? {} : { tile: input.tile }),
+        ...(input.area === undefined ? {} : { area: input.area }),
         ...(context.principal === undefined ? {} : { principal: context.principal }),
         ...(context.signal === undefined ? {} : { signal: context.signal }),
     });
@@ -483,6 +548,7 @@ export async function renderMapView(nudger, input, context) {
         height: rendered.bundle.height,
         hashes: rendered.bundle.hashes,
         offlineRepresentation: true,
+        ...(rendered.bundle.tile === undefined ? {} : { tile: rendered.bundle.tile }),
     });
     result.code = 'MAP_RENDERED';
     setInlineFilesScanned(result, rendered.filesScanned);

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

@@ -31,6 +31,7 @@ const eventRenderInputSchema = z
 const eventCompareInputSchema = z
     .object({
     ...eventCompareRequestSchema.shape,
+    selector: nestedSelectorSchema.optional(),
     before: nestedGraphReferenceSchema.optional(),
     after: nestedGraphReferenceSchema.optional(),
     proposedSources: z.array(nestedProposedSourceSchema).min(1).max(64).optional(),
@@ -119,6 +120,11 @@ const eventCompareOutputSchema = strictOperationResultSchema(z
     counts: z
         .object({
         changes: nonNegativeIntegerSchema,
+        selectedChanges: nonNegativeIntegerSchema.optional(),
+        omittedChanges: nonNegativeIntegerSchema.optional(),
+        unattributedChanges: nonNegativeIntegerSchema.optional(),
+        selectedBeforeNodes: nonNegativeIntegerSchema.optional(),
+        selectedAfterNodes: nonNegativeIntegerSchema.optional(),
         addedNodes: nonNegativeIntegerSchema,
         removedNodes: nonNegativeIntegerSchema,
         changedNodes: nonNegativeIntegerSchema,
@@ -146,6 +152,9 @@ const eventCompareOutputSchema = strictOperationResultSchema(z
     boundary: z
         .object({
         proposedSources: nonNegativeIntegerSchema,
+        selector: eventSelectorSchema.optional(),
+        maxChainNodes: nonNegativeIntegerSchema.optional(),
+        selectionTruncated: z.boolean().optional(),
         render: z.boolean(),
         maxRenderNodes: nonNegativeIntegerSchema,
         refresh: z.boolean(),
@@ -179,7 +188,7 @@ export const eventTaskTools = [
     {
         name: 'hoi4.event_compare',
         title: 'Compare event chains',
-        description: 'Compare cached, artifact-backed, current, or in-memory proposed event graphs without writing source. Full changes are resources.',
+        description: 'Compare cached, artifact-backed, current, or in-memory proposed event graphs, optionally selecting one downstream chain. Full changes and explicit selection coverage are resources.',
         inputSchema: eventCompareInputSchema,
         outputSchema: eventCompareOutputSchema,
         annotations: readOnlyEventTool,

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

@@ -30,6 +30,16 @@ const focusInspectOutputSchema = strictOperationResultSchema(z
         layoutDecisionCount: nonNegativeIntegerSchema,
         layoutMetrics: focusLayoutMetricsSchema,
         diagnosticCount: nonNegativeIntegerSchema,
+        scenarioSummary: z
+            .object({
+            completed: nonNegativeIntegerSchema,
+            blocked: nonNegativeIntegerSchema,
+            unresolved: nonNegativeIntegerSchema,
+            structuralCandidates: nonNegativeIntegerSchema,
+            choiceConflictCount: nonNegativeIntegerSchema,
+        })
+            .strict()
+            .optional(),
     })
         .strict())
         .max(100),
@@ -125,7 +135,7 @@ export const focusTaskTools = [
     {
         name: 'hoi4.focus_inspect',
         title: 'Inspect focus trees',
-        description: 'Inspect national trees or continuous palettes for creation and cleanup, including continuous-focus placement, complete plans, references, diagnostics, and stable layout decisions.',
+        description: 'Inspect focus trees and continuous palettes, including source references, diagnostics, and layout.',
         inputSchema: focusInspectRequestSchema,
         outputSchema: focusInspectOutputSchema,
         annotations: artifactProducing,
@@ -133,7 +143,7 @@ export const focusTaskTools = [
     {
         name: 'hoi4.focus_render',
         title: 'Render focus review artifacts',
-        description: 'Render a national tree or continuous palette as fast deterministic HTML, SVG, JSON, and source-map artifacts. Use hoi4.focus_raster when decoded icons and PNG output are needed.',
+        description: 'Render focus HTML, SVG, JSON, and source maps. Use hoi4.focus_raster for decoded icons and PNG.',
         inputSchema: focusRenderRequestSchema,
         outputSchema: focusRenderOutputSchema,
         annotations: artifactProducing,
@@ -141,7 +151,7 @@ export const focusTaskTools = [
     {
         name: 'hoi4.focus_raster',
         title: 'Rasterize focus review artifacts',
-        description: 'Produce the high-fidelity focus review with decoded source icons and deterministic PNG output. Use focus_render for the faster structural HTML, SVG, and JSON view.',
+        description: 'Render focus PNG with decoded source icons; also returns HTML, SVG, and JSON.',
         inputSchema: focusRenderRequestSchema,
         outputSchema: focusRenderOutputSchema,
         annotations: artifactProducing,
@@ -149,7 +159,7 @@ export const focusTaskTools = [
     {
         name: 'hoi4.focus_rewrite',
         title: 'Create or clean up focus content',
-        description: 'Create or clean up a national tree or continuous palette, validate it, and apply it in one call. Supply a complete plan; set layoutMode compact for automatic arrangement. Existing national trees can omit the plan and use treeId plus layoutMode compact. Set createIfMissing for a new file.',
+        description: 'Create or compact a focus tree or palette from a complete plan. Use treeId for existing trees and createIfMissing for new files.',
         inputSchema: focusRewriteRequestSchema,
         outputSchema: focusPlanOutputSchema,
         annotations: {

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

@@ -43,6 +43,10 @@ const guiRenderOutputSchema = strictOperationResultSchema(z
     comparison: z
         .object({ changedPixels: nonNegativeIntegerSchema, changedRatio: z.number().min(0).max(1) })
         .strict(),
+    sourceComparison: z
+        .object({ changedPixels: nonNegativeIntegerSchema, changedRatio: z.number().min(0).max(1) })
+        .strict()
+        .optional(),
     fidelityCounts: countRecordSchema,
     offlineRepresentation: z.literal(true),
 })
@@ -76,7 +80,7 @@ export const guiTaskTools = [
     {
         name: 'hoi4.gui_render',
         title: 'Render scripted GUI artifacts',
-        description: 'Render GUI states, resolutions, generated or explicit scenarios, dynamic flags and text icons, hierarchy, comparisons, and diagnostics.',
+        description: 'Render GUI states, resolutions, scenarios, hierarchy, comparisons, and diagnostics.',
         inputSchema: guiRenderRequestSchema,
         outputSchema: guiRenderOutputSchema,
         annotations: artifactProducing,

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

@@ -75,6 +75,7 @@ const mapWorkspaceInspectOutputSchema = strictOperationResultSchema(z
     provinceGeometryCount: nonNegativeIntegerSchema,
     provinceGeometryPixelCount: nonNegativeIntegerSchema,
     provinceGeometryRowRunCount: nonNegativeIntegerSchema,
+    lookupOnly: z.boolean().optional(),
     unknownProvinceIds: z.array(nonNegativeIntegerSchema).max(512),
     missingGeometryProvinceIds: z.array(nonNegativeIntegerSchema).max(512),
 })
@@ -86,6 +87,15 @@ const mapRenderOutputSchema = strictOperationResultSchema(z
     height: nonNegativeIntegerSchema,
     hashes: bitmapRenderHashesSchema,
     offlineRepresentation: z.literal(true),
+    tile: z
+        .object({
+        x: nonNegativeIntegerSchema,
+        y: nonNegativeIntegerSchema,
+        width: nonNegativeIntegerSchema,
+        height: nonNegativeIntegerSchema,
+    })
+        .strict()
+        .optional(),
 })
     .strict());
 const mapPlanOutputSchema = strictOperationResultSchema(z
@@ -113,7 +123,7 @@ export const mapTaskTools = [
     {
         name: 'hoi4.map_inspect',
         title: 'Inspect HOI4 map',
-        description: 'Render, validate, search, and click the complete map.',
+        description: 'Validate and inspect the complete map, or use lookupOnly for bounded coordinate and entity lookups.',
         inputSchema: mapInspectRequestSchema,
         outputSchema: mapWorkspaceInspectOutputSchema,
         annotations: artifactProducing,
@@ -121,7 +131,7 @@ export const mapTaskTools = [
     {
         name: 'hoi4.map_render',
         title: 'Render map inspection artifacts',
-        description: 'Render searchable full-map PNG, JSON, and HTML.',
+        description: 'Render searchable full-map PNG, JSON, and HTML, or a reusable source-coordinate tile.',
         inputSchema: mapRenderRequestSchema,
         outputSchema: mapRenderOutputSchema,
         annotations: artifactProducing,

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

@@ -16,6 +16,9 @@ const analysisDataSchema = z
     cacheKey: sha256Schema,
     scenarios: nonNegativeIntegerSchema,
     candidates: nonNegativeIntegerSchema,
+    eligibleCandidates: nonNegativeIntegerSchema,
+    excludedCandidates: nonNegativeIntegerSchema,
+    unresolvedCandidates: nonNegativeIntegerSchema,
     scopePools: nonNegativeIntegerSchema.optional(),
     scopePoolCandidates: nonNegativeIntegerSchema.optional(),
     unresolved: nonNegativeIntegerSchema,
@@ -61,6 +64,8 @@ const inspectDataSchema = z
     candidateExamples: z.array(z.string().max(512)).max(10),
     poolComplete: z.boolean().optional(),
     requiredInputs: nonNegativeIntegerSchema,
+    requiredInputPaths: z.array(z.string().max(1024)).max(32),
+    requiredInputPathsTruncated: z.boolean(),
     unresolved: nonNegativeIntegerSchema,
 })
     .strict();

package/dist/hoi4_agent_tools/mechanic/interpreter.js

@@ -13,6 +13,22 @@ const numericEffects = new Map([
     ['add_war_support', { key: 'war_support', mode: 'add', min: 0, max: 1 }],
 ]);
 const harmlessEffects = new Set(['hidden_effect', 'custom_effect_tooltip', 'log', 'tooltip']);
+const variableEffects = new Map([
+    ['set_variable', 'set'],
+    ['set_temp_variable', 'set'],
+    ['add_to_variable', 'add'],
+    ['add_to_temp_variable', 'add'],
+    ['subtract_from_variable', 'subtract'],
+    ['subtract_from_temp_variable', 'subtract'],
+    ['multiply_variable', 'multiply'],
+    ['multiply_temp_variable', 'multiply'],
+    ['divide_variable', 'divide'],
+    ['divide_temp_variable', 'divide'],
+    ['clamp_variable', 'clamp'],
+    ['clamp_temp_variable', 'clamp'],
+    ['round_variable', 'round'],
+    ['round_temp_variable', 'round'],
+]);
 function numeric(value) {
     if (typeof value === 'number' && Number.isFinite(value))
         return value;
@@ -175,6 +191,40 @@ export class MechanicInterpreter {
         return (numeric(scenarioValue(this.state, key, targetScope)) ??
             numeric(scenarioValue(this.state, `variable.${key}`, targetScope)));
     }
+    scopeReference(expression, scope, stack) {
+        const scopeId = (name) => {
+            if (name === 'ROOT')
+                return this.state.scenario.actor ?? 'ROOT';
+            if (name === 'THIS')
+                return scope === 'ROOT'
+                    ? (this.state.scenario.actor ?? 'ROOT')
+                    : this.state.scenario.scopes?.[scope]?.id;
+            if (name === 'PREV') {
+                const previous = stack.findLast((item) => item.startsWith('scope:'))?.slice(6);
+                return previous === undefined
+                    ? undefined
+                    : previous === 'ROOT'
+                        ? (this.state.scenario.actor ?? 'ROOT')
+                        : this.state.scenario.scopes?.[previous]?.id;
+            }
+            return this.state.scenario.scopes?.[name]?.id;
+        };
+        if (expression.startsWith('event_target:'))
+            return this.state.scenario.eventTargets?.[expression.slice(13)];
+        const identifier = /^([A-Za-z0-9_:]+)(?:\.id)?$/u.exec(expression)?.[1];
+        return identifier === undefined ? undefined : scopeId(identifier.toUpperCase());
+    }
+    value(expression, path, scope, stack) {
+        const numberValue = this.number(expression, path, scope);
+        if (numberValue !== undefined)
+            return numberValue;
+        const dotted = /^(ROOT|THIS|FROM|PREV)\.(.+)$/iu.exec(expression);
+        const targetScope = dotted?.[1]?.toUpperCase() === 'THIS' ? scope : (dotted?.[1]?.toUpperCase() ?? scope);
+        const key = dotted?.[2] ?? expression;
+        const existing = scenarioValue(this.state, key, targetScope) ??
+            scenarioValue(this.state, `variable.${key}`, targetScope);
+        return existing ?? this.scopeReference(expression, scope, stack);
+    }
     mathExpression(block, path, scope) {
         const entries = entriesOnly(block);
         if (entries === undefined || entries[0]?.key.value !== 'value')
@@ -410,42 +460,53 @@ export class MechanicInterpreter {
             }
             return;
         }
-        if ([
-            'set_variable',
-            'add_to_variable',
-            'subtract_from_variable',
-            'multiply_variable',
-            'divide_variable',
-            'clamp_variable',
-        ].includes(key)) {
+        const variableMode = variableEffects.get(key);
+        if (variableMode !== undefined) {
+            const variableScope = key.includes('temp_variable') ? 'ROOT' : scope;
+            const scalarVariable = asText(entry.value);
+            if (variableMode === 'round') {
+                const variable = scalarVariable ?? (child === undefined ? undefined : firstScalar(child, 'var')?.value);
+                const before = variable === undefined
+                    ? undefined
+                    : numeric(scenarioValue(this.state, variable, variableScope));
+                const after = before === undefined ? undefined : Math.round(before);
+                if (variable === undefined) {
+                    this.unknown(key, path, scope, 'Variable must resolve');
+                    return;
+                }
+                setScenarioValue(this.state, variable, after, variableScope);
+                this.note(key, path, scope, after === undefined ? 'unresolved' : 'applied', before, after, after === undefined ? 'Variable value is not numeric' : undefined, variable);
+                return;
+            }
             if (child === undefined) {
                 this.unknown(key, path, scope, 'Variable effect requires a block');
                 return;
             }
             const short = assignments(child).find((item) => !['var', 'value', 'min', 'max', 'tooltip'].includes(item.key.value));
             const variable = firstScalar(child, 'var')?.value ?? short?.key.value;
+            if (variable === undefined) {
+                this.unknown(key, path, scope, 'Variable must resolve');
+                return;
+            }
             const expression = firstScalar(child, 'value')?.value ??
                 (short === undefined ? undefined : asText(short.value));
-            if (variable === undefined || expression === undefined) {
-                if (variable === undefined || short?.value.type !== 'block') {
-                    this.unknown(key, path, scope, 'Variable and operand must resolve');
-                    return;
-                }
-            }
-            const value = expression === undefined
-                ? this.mathExpression(short.value, path, scope)
-                : this.number(expression, path, scope);
-            const before = numeric(scenarioValue(this.state, variable, scope)) ?? 0;
-            let after = value;
-            if (value !== undefined && key === 'add_to_variable')
-                after = before + value;
-            if (value !== undefined && key === 'subtract_from_variable')
-                after = before - value;
-            if (value !== undefined && key === 'multiply_variable')
-                after = before * value;
-            if (value !== undefined && key === 'divide_variable')
-                after = value === 0 ? undefined : before / value;
-            if (value !== undefined && key === 'clamp_variable') {
+            const operand = expression === undefined
+                ? variableMode === 'set' && short?.value.type === 'block'
+                    ? this.mathExpression(short.value, path, scope)
+                    : undefined
+                : this.value(expression, path, scope, stack);
+            const previous = scenarioValue(this.state, variable, variableScope);
+            const before = numeric(previous) ?? 0;
+            let after = variableMode === 'set' ? operand : numeric(operand);
+            if (variableMode === 'add' && typeof after === 'number')
+                after = before + after;
+            if (variableMode === 'subtract' && typeof after === 'number')
+                after = before - after;
+            if (variableMode === 'multiply' && typeof after === 'number')
+                after = before * after;
+            if (variableMode === 'divide' && typeof after === 'number')
+                after = after === 0 ? undefined : before / after;
+            if (variableMode === 'clamp') {
                 const minimum = firstScalar(child, 'min')?.value;
                 const maximum = firstScalar(child, 'max')?.value;
                 const min = minimum === undefined ? -Infinity : this.number(minimum, path, scope);
@@ -453,8 +514,8 @@ export class MechanicInterpreter {
                 after =
                     min === undefined || max === undefined ? undefined : Math.max(min, Math.min(max, before));
             }
-            setScenarioValue(this.state, variable, after, scope);
-            this.note(key, path, scope, after === undefined ? 'unresolved' : 'applied', before, after, after === undefined ? 'Numeric operand is unknown or division by zero' : undefined, variable);
+            setScenarioValue(this.state, variable, after, variableScope);
+            this.note(key, path, scope, after === undefined ? 'unresolved' : 'applied', previous, after, after === undefined ? 'Numeric operand is unknown or division by zero' : undefined, variable);
             return;
         }
         if (key === 'set_country_flag' ||

package/dist/hoi4_agent_tools/mechanic/source.js

@@ -77,13 +77,28 @@ export function selectMechanicSource(snapshot, selector) {
 }
 export function scriptedEffectSources(snapshot) {
     const result = new Map();
+    const symbolsByPath = new Map();
     for (const symbol of snapshot.index.symbols) {
         if (symbol.kind !== 'scripted_effect' || symbol.overridden || symbol.sourceShadowed)
             continue;
-        const document = activeDocument(snapshot, symbol.path);
-        const block = document === undefined ? undefined : assignments(document.root, symbol.id)[0]?.value;
-        if (block?.type === 'block')
-            result.set(symbol.id, { id: symbol.id, path: symbol.path, block });
+        const symbols = symbolsByPath.get(symbol.path) ?? [];
+        symbols.push(symbol);
+        symbolsByPath.set(symbol.path, symbols);
+    }
+    for (const [sourcePath, symbols] of symbolsByPath) {
+        const document = activeDocument(snapshot, sourcePath);
+        if (document === undefined)
+            continue;
+        const blocks = new Map();
+        for (const definition of assignments(document.root)) {
+            if (definition.value.type === 'block' && !blocks.has(definition.key.value))
+                blocks.set(definition.key.value, definition.value);
+        }
+        for (const symbol of symbols) {
+            const block = blocks.get(symbol.id);
+            if (block !== undefined)
+                result.set(symbol.id, { id: symbol.id, path: symbol.path, block });
+        }
     }
     return result;
 }

package/dist/hoi4_agent_tools/probability/evaluation.js

@@ -114,6 +114,9 @@ export function evaluateExactCandidates(surface, scenario, definitions) {
                 ...external.trace,
             ],
             unresolved: [...eligibility.unresolved, ...value.unresolved, ...external.unresolved],
+            eligibilityUnresolved: eligibility.unresolved,
+            valueUnresolved: value.unresolved,
+            externalUnresolved: external.unresolved,
             provenance: [
                 ...candidate.provenance,
                 ...(eligibility.helperProvenance ?? []),