hoi4-agent-tools 2.7.0 → 2.8.0

package/CHANGELOG.md

@@ -4,6 +4,13 @@
 
 No unreleased changes.
 
+## 2.8.0 - 2026-08-26
+
+- Added structured `ROOT`, `THIS`, `PREV`, `FROM` chain, saved-scope, and event-target bindings to probability scenarios.
+- Added deterministic enumeration and exact complete-pool shares for declared dynamic destination, opposition, donor, and other runtime scope pools.
+- Extended exact branching, sweeps, and simulation to update scoped and pool-candidate state without flattening it into the root scenario.
+- Added MCP resource counts, a published callable example, 2,048-candidate coverage, and source-linked trigger traces for dynamic scope pools.
+
 ## 2.7.0 - 2026-08-24
 
 - Made scripted-GUI layout follow Clausewitz orientation, element-origin, center-position, relative-dimension, local-scale, container-clipping, and fixed text-bound behavior.

package/README.md

@@ -9,7 +9,7 @@ HOI4 Agent Tools is an MCP server for coding agents to understand Hearts of Iron
 - Maps: navigate the complete rendered map by ID or localised name; inspect provinces, states, regions, adjacency, supply, railways, and positions; create states and provinces; change IDs; and repair connected 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.
+- AI and MTTH: evaluate weighted choices and timing across explicit scenarios, bind special scope chains, enumerate dynamic target pools, sweep uncertain inputs, simulate distributions, compare patches, and analyze declared stateful pools.
 
 ## Setup
 

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

@@ -120,6 +120,8 @@ const analysisDataSchema = z
     cacheKey: sha256Schema,
     scenarios: nonNegativeIntegerSchema,
     candidates: nonNegativeIntegerSchema,
+    scopePools: nonNegativeIntegerSchema.optional(),
+    scopePoolCandidates: nonNegativeIntegerSchema.optional(),
     unresolved: nonNegativeIntegerSchema,
     diagnostics: nonNegativeIntegerSchema,
     sweepPoints: nonNegativeIntegerSchema.optional(),
@@ -194,6 +196,13 @@ function analysisData(result) {
         cacheKey: result.metadata.cacheKey,
         scenarios: result.scenarios.length,
         candidates: result.scenarios.reduce((sum, scenario) => sum + scenario.candidates.length, 0),
+        ...(result.scenarios.some(({ scopePools }) => (scopePools?.length ?? 0) > 0)
+            ? {
+                scopePools: result.scenarios.reduce((sum, scenario) => sum + (scenario.scopePools?.length ?? 0), 0),
+                scopePoolCandidates: result.scenarios.reduce((sum, scenario) => sum +
+                    (scenario.scopePools?.reduce((poolSum, pool) => poolSum + pool.candidates.length, 0) ?? 0), 0),
+            }
+            : {}),
         unresolved: result.unresolved.length,
         diagnostics: result.diagnostics.length,
         ...(result.sweep === undefined ? {} : { sweepPoints: result.sweep.points.length }),

package/dist/hoi4_agent_tools/probability/adapters.js

@@ -326,6 +326,11 @@ const descriptors = Object.fromEntries(Object.entries(sources).map(([id, source]
             'Apply declared external factors only after source-local operations.',
         ],
         poolNormalizationRules: normalizationRule(source.selectionRule),
+        supportedExpressions: [
+            ...source.supportedExpressions,
+            'scenario-bound ROOT/THIS/PREV/FROM scope chains, saved scopes, and event targets',
+            'declared dynamic scope-pool filters with uniform or proportional selection',
+        ],
         timingConversion: source.selectionRule === 'median_daily_hazard'
             ? [
                 'Treat the effective duration as the median of verified daily checks while active.',

package/dist/hoi4_agent_tools/probability/evaluation.js

@@ -1,6 +1,8 @@
 import { compareCodeUnits } from '../core/canonical.js';
 import { assignments } from '../core/source/index.js';
 import { Rational, sumRationals, uniformRaceProbabilities } from './rational.js';
+import { withScenarioPathValue } from './scenario-state.js';
+import { evaluateScopePools } from './scope-pools.js';
 import { evaluateTriggerBlock } from './trigger-evaluator.js';
 import { evaluateCandidateValue } from './value-evaluator.js';
 const BRANCH_LIMIT = 4_096;
@@ -305,7 +307,7 @@ function scenarioBranches(surface, scenario) {
             });
             break;
         }
-        branches = branches.flatMap((branch) => values.map((value) => ({ ...branch, state: { ...branch.state, [input.path]: value } })));
+        branches = branches.flatMap((branch) => values.map((value) => withScenarioPathValue(branch, input.path, value)));
         if (values.length > 1)
             bounded = true;
     }
@@ -599,10 +601,12 @@ export function evaluateSurfaceScenarios(surface, scenarios, definitions, horizo
             return result;
         });
         rankCandidates(candidates);
+        const scopePools = evaluateScopePools(scenario, definitions);
         const allUnresolved = [
             ...surface.unsupported,
             ...expanded.unresolved,
             ...candidates.flatMap(({ unresolved }) => unresolved),
+            ...scopePools.flatMap(({ unresolved }) => unresolved),
         ];
         const timing = horizonDays === undefined
             ? { unresolved: [] }
@@ -632,6 +636,7 @@ export function evaluateSurfaceScenarios(surface, scenarios, definitions, horizo
                             ? 'score_only'
                             : 'exact',
             candidates,
+            ...(scopePools.length === 0 ? {} : { scopePools }),
             ...(exactValues.length === candidates.length &&
                 surface.adapter.selectionRule === 'proportional_categorical'
                 ? { poolTotal: sumRationals(exactValues).toJSON() }

package/dist/hoi4_agent_tools/probability/scenario-state.js

@@ -0,0 +1,165 @@
+function caseInsensitiveEntry(record, key) {
+    if (record === undefined)
+        return undefined;
+    if (Object.hasOwn(record, key))
+        return record[key];
+    const normalized = key.toLowerCase();
+    const found = Object.entries(record).find(([candidate]) => candidate.toLowerCase() === normalized);
+    return found?.[1];
+}
+export function rootScopeContext(scenario) {
+    return {
+        expression: 'ROOT',
+        binding: {
+            id: scenario.actor ?? 'ROOT',
+            ...(scenario.actor === undefined ? {} : { actor: scenario.actor }),
+            state: scenario.state,
+            ...(scenario.flags === undefined ? {} : { flags: scenario.flags }),
+            ...(scenario.eventTargets === undefined ? {} : { eventTargets: scenario.eventTargets }),
+        },
+    };
+}
+function explicitScope(scenario, expression, parent) {
+    const binding = caseInsensitiveEntry(scenario.scopes, expression);
+    return binding === undefined ? undefined : { expression, binding, parent };
+}
+export function resolveScopeContext(scenario, expression, current) {
+    const upper = expression.toUpperCase();
+    if (upper === 'ROOT')
+        return rootScopeContext(scenario);
+    if (upper === 'THIS')
+        return current;
+    if (upper === 'PREV')
+        return current.parent ?? rootScopeContext(scenario);
+    const chained = current.expression === 'ROOT' || current.expression === 'THIS'
+        ? expression
+        : `${current.expression}.${expression}`;
+    const chainedBinding = explicitScope(scenario, chained, current);
+    if (chainedBinding !== undefined)
+        return chainedBinding;
+    const direct = explicitScope(scenario, expression, current);
+    if (direct !== undefined)
+        return direct;
+    const targetMatch = /^(?:event_target|scope):(.+)$/iu.exec(expression);
+    const targetId = targetMatch === null
+        ? undefined
+        : (caseInsensitiveEntry(current.binding.eventTargets, targetMatch[1]) ??
+            caseInsensitiveEntry(scenario.eventTargets, targetMatch[1]));
+    if (targetId !== undefined) {
+        const declaredBinding = Object.values(scenario.scopes ?? {}).find((binding) => binding.id === targetId || binding.actor === targetId);
+        return {
+            expression,
+            binding: declaredBinding ?? { id: targetId, actor: targetId, state: {} },
+            parent: current,
+        };
+    }
+    return undefined;
+}
+export function scopeStateValue(scenario, key, current) {
+    if (Object.hasOwn(current.binding.state, key))
+        return current.binding.state[key];
+    if (Object.hasOwn(current.binding.state, `trigger.${key}`))
+        return current.binding.state[`trigger.${key}`];
+    if (current.expression !== 'ROOT')
+        return undefined;
+    if (Object.hasOwn(scenario.state, key))
+        return scenario.state[key];
+    if (Object.hasOwn(scenario.state, `trigger.${key}`))
+        return scenario.state[`trigger.${key}`];
+    return undefined;
+}
+export function rootStateValue(scenario, key) {
+    if (Object.hasOwn(scenario.state, key))
+        return scenario.state[key];
+    if (Object.hasOwn(scenario.state, `trigger.${key}`))
+        return scenario.state[`trigger.${key}`];
+    return undefined;
+}
+export function scopeIdentity(current) {
+    return current.binding.actor ?? current.binding.id;
+}
+export function scopedExpressionValue(scenario, expression) {
+    const scopes = Object.entries(scenario.scopes ?? {}).sort(([left], [right]) => right.length - left.length);
+    for (const [scope, binding] of scopes) {
+        for (const prefix of [`${scope}.`, `scope.${scope}.`, `scopes.${scope}.`]) {
+            if (!expression.toLowerCase().startsWith(prefix.toLowerCase()))
+                continue;
+            const key = expression.slice(prefix.length).replace(/^state\./u, '');
+            if (Object.hasOwn(binding.state, key))
+                return binding.state[key];
+            if (Object.hasOwn(binding.state, `variable.${key}`))
+                return binding.state[`variable.${key}`];
+        }
+    }
+    return undefined;
+}
+function updateScopeState(scenario, path, value) {
+    const scopes = Object.entries(scenario.scopes ?? {}).sort(([left], [right]) => right.length - left.length);
+    for (const [scope, binding] of scopes) {
+        for (const prefix of [`scope.${scope}.`, `scopes.${scope}.`]) {
+            if (!path.toLowerCase().startsWith(prefix.toLowerCase()))
+                continue;
+            const key = path.slice(prefix.length).replace(/^state\./u, '');
+            return {
+                ...scenario,
+                scopes: {
+                    ...scenario.scopes,
+                    [scope]: { ...binding, state: { ...binding.state, [key]: value } },
+                },
+            };
+        }
+    }
+    return undefined;
+}
+function updatePoolCandidateState(scenario, path, value) {
+    if (!path.startsWith('scopePools.'))
+        return undefined;
+    for (const [poolIndex, pool] of (scenario.scopePools ?? []).entries()) {
+        const poolPrefix = `scopePools.${pool.id}.`;
+        if (!path.startsWith(poolPrefix))
+            continue;
+        for (const [candidateIndex, candidate] of pool.candidates.entries()) {
+            const candidatePrefix = `${poolPrefix}${candidate.id}.`;
+            if (!path.startsWith(candidatePrefix))
+                continue;
+            const key = path.slice(candidatePrefix.length).replace(/^state\./u, '');
+            const candidates = [...pool.candidates];
+            candidates[candidateIndex] = {
+                ...candidate,
+                state: { ...candidate.state, [key]: value },
+            };
+            const pools = [...(scenario.scopePools ?? [])];
+            pools[poolIndex] = { ...pool, candidates };
+            return { ...scenario, scopePools: pools };
+        }
+    }
+    return undefined;
+}
+export function scenarioPathValue(scenario, path) {
+    const scoped = scopedExpressionValue(scenario, path);
+    if (scoped !== undefined)
+        return scoped;
+    if (path.startsWith('scopePools.')) {
+        for (const pool of scenario.scopePools ?? []) {
+            const poolPrefix = `scopePools.${pool.id}.`;
+            if (!path.startsWith(poolPrefix))
+                continue;
+            for (const candidate of pool.candidates) {
+                const candidatePrefix = `${poolPrefix}${candidate.id}.`;
+                if (!path.startsWith(candidatePrefix))
+                    continue;
+                const key = path.slice(candidatePrefix.length).replace(/^state\./u, '');
+                if (Object.hasOwn(candidate.state, key))
+                    return candidate.state[key];
+            }
+        }
+    }
+    return rootStateValue(scenario, path);
+}
+export function withScenarioPathValue(scenario, path, value) {
+    return (updateScopeState(scenario, path, value) ??
+        updatePoolCandidateState(scenario, path, value) ?? {
+        ...scenario,
+        state: { ...scenario.state, [path]: value },
+    });
+}

package/dist/hoi4_agent_tools/probability/scope-pools.js

@@ -0,0 +1,199 @@
+import { compareCodeUnits, hashCanonical } from '../core/canonical.js';
+import { childBlocks, parseClausewitz, } from '../core/source/index.js';
+import { Rational, sumRationals } from './rational.js';
+import { rootScopeContext, scopedExpressionValue, } from './scenario-state.js';
+import { evaluateTriggerBlock } from './trigger-evaluator.js';
+function filterSource(pool) {
+    if (pool.filter?.scriptedTrigger !== undefined)
+        return `filter = { ${pool.filter.scriptedTrigger} = yes }`;
+    const inline = pool.filter?.inlineClausewitz?.trim();
+    if (inline === undefined)
+        return undefined;
+    if (/^filter\s*=/iu.test(inline))
+        return inline;
+    return inline.startsWith('{') ? `filter = ${inline}` : `filter = { ${inline} }`;
+}
+function parseFilter(scenario, pool) {
+    const source = filterSource(pool);
+    const sourceHash = hashCanonical({ scenarioId: scenario.id, poolId: pool.id, source });
+    if (source === undefined)
+        return { sourceHash, unresolved: [] };
+    const path = `scenario:${scenario.id}/scope-pool:${pool.id}`;
+    try {
+        const document = parseClausewitz(Buffer.from(source, 'utf8'), path);
+        const block = childBlocks(document.root, 'filter')[0];
+        if (block !== undefined)
+            return { document, block, sourceHash, unresolved: [] };
+    }
+    catch (error) {
+        return {
+            sourceHash,
+            unresolved: [
+                {
+                    code: 'SCOPE_POOL_FILTER_INVALID',
+                    message: `Scope pool ${pool.id} filter could not be parsed`,
+                    path: pool.id,
+                    details: { reason: error instanceof Error ? error.message : String(error) },
+                },
+            ],
+        };
+    }
+    return {
+        sourceHash,
+        unresolved: [
+            {
+                code: 'SCOPE_POOL_FILTER_INVALID',
+                message: `Scope pool ${pool.id} filter does not contain a trigger block`,
+                path: pool.id,
+            },
+        ],
+    };
+}
+function scopedScenario(scenario, pool, binding) {
+    const bindAs = pool.bindAs ?? 'THIS';
+    if (bindAs === 'ROOT') {
+        const root = {
+            ...scenario,
+            actor: binding.actor ?? binding.id,
+            state: binding.state,
+            ...(binding.flags === undefined ? {} : { flags: binding.flags }),
+            ...(binding.eventTargets === undefined ? {} : { eventTargets: binding.eventTargets }),
+            scopes: { ...scenario.scopes, ROOT: binding, THIS: binding },
+        };
+        return { scenario: root, context: rootScopeContext(root) };
+    }
+    const selected = {
+        ...scenario,
+        scopes: {
+            ...scenario.scopes,
+            THIS: binding,
+            [bindAs]: binding,
+        },
+    };
+    return {
+        scenario: selected,
+        context: {
+            expression: 'THIS',
+            binding,
+            parent: rootScopeContext(scenario),
+        },
+    };
+}
+function candidateFor(scenario, pool, binding, filter) {
+    return {
+        id: binding.id,
+        adapterId: 'custom_weighted_pool',
+        sourceKind: 'dynamic_scope_pool_candidate',
+        defaultValue: '1',
+        ...(filter.document === undefined ? {} : { document: filter.document }),
+        provenance: [
+            {
+                path: `scenario:${scenario.id}/scope-pool:${pool.id}`,
+                rootKind: 'scenario',
+                loadOrder: 0,
+                sourceHash: filter.sourceHash,
+                symbol: binding.id,
+            },
+        ],
+        metadata: { poolId: pool.id, bindAs: pool.bindAs ?? 'THIS' },
+    };
+}
+function poolWeight(pool, binding, scenario) {
+    if (pool.selection === 'uniform')
+        return Rational.one;
+    const expression = binding.weight ?? 1;
+    const direct = Rational.parse(expression);
+    if (direct !== undefined)
+        return direct.compare(Rational.zero) < 0 ? undefined : direct;
+    if (typeof expression !== 'string')
+        return undefined;
+    const value = binding.state[expression] ??
+        binding.state[`variable.${expression}`] ??
+        scopedExpressionValue(scenario, expression) ??
+        scenario.state[expression] ??
+        scenario.state[`variable.${expression}`];
+    const parsed = typeof value === 'number' || typeof value === 'string' ? Rational.parse(value) : undefined;
+    return parsed !== undefined && parsed.compare(Rational.zero) >= 0 ? parsed : undefined;
+}
+function evaluatePool(scenario, pool, definitions) {
+    const filter = parseFilter(scenario, pool);
+    const candidates = [...pool.candidates]
+        .sort((left, right) => compareCodeUnits(left.id, right.id))
+        .map((binding) => {
+        const selected = scopedScenario(scenario, pool, binding);
+        const candidate = candidateFor(scenario, pool, binding, filter);
+        const eligibility = filter.unresolved.length > 0
+            ? { state: 'unresolved', unresolved: filter.unresolved }
+            : evaluateTriggerBlock(filter.block, selected.scenario, candidate, definitions, [], selected.context);
+        const unresolved = [...eligibility.unresolved];
+        const weight = pool.selection === 'enumeration' ? undefined : poolWeight(pool, binding, selected.scenario);
+        if (pool.selection !== 'enumeration' && weight === undefined)
+            unresolved.push({
+                code: 'SCOPE_POOL_WEIGHT_UNRESOLVED',
+                message: `Scope pool ${pool.id} candidate ${binding.id} has an unresolved weight`,
+                path: pool.id,
+                candidateId: binding.id,
+                details: { weight: binding.weight ?? 1 },
+            });
+        return {
+            id: binding.id,
+            eligibility: eligibility.state,
+            ...(weight === undefined ? {} : { weight: weight.toJSON() }),
+            trace: eligibility.trace ?? [],
+            unresolved,
+        };
+    });
+    const unresolved = [
+        ...filter.unresolved,
+        ...candidates.flatMap(({ unresolved: items }) => items),
+    ];
+    if (pool.selection !== 'enumeration' && !pool.complete)
+        unresolved.push({
+            code: 'SCOPE_POOL_INCOMPLETE',
+            message: `Scope pool ${pool.id} can be enumerated, but normalized probabilities require a complete candidate catalog`,
+            path: pool.id,
+        });
+    const resolved = candidates.every(({ eligibility, weight }) => eligibility !== 'unresolved' && (pool.selection === 'enumeration' || weight !== undefined));
+    const eligibleWeights = candidates.flatMap((candidate) => candidate.eligibility === 'true' && candidate.weight !== undefined
+        ? [Rational.parse(candidate.weight.decimal)]
+        : []);
+    const total = sumRationals(eligibleWeights);
+    if (pool.selection !== 'enumeration' &&
+        pool.complete &&
+        resolved &&
+        total.compare(Rational.zero) > 0) {
+        for (const candidate of candidates) {
+            const probability = candidate.eligibility === 'true' && candidate.weight !== undefined
+                ? Rational.parse(candidate.weight.decimal).divide(total)
+                : Rational.zero;
+            candidate.conditionalProbability = probability.toNumber();
+            candidate.exactConditionalProbability = probability.toJSON();
+        }
+    }
+    else if (pool.selection !== 'enumeration' && pool.complete && resolved && total.isZero())
+        unresolved.push({
+            code: 'SCOPE_POOL_ZERO_TOTAL',
+            message: `Scope pool ${pool.id} has no positive eligible weight`,
+            path: pool.id,
+        });
+    return {
+        id: pool.id,
+        bindAs: pool.bindAs ?? 'THIS',
+        selection: pool.selection,
+        poolComplete: pool.complete,
+        candidates,
+        eligibleCandidateIds: candidates
+            .filter(({ eligibility }) => eligibility === 'true')
+            .map(({ id }) => id),
+        unresolvedCandidateIds: candidates
+            .filter(({ eligibility, unresolved: items }) => eligibility === 'unresolved' || items.length > 0)
+            .map(({ id }) => id),
+        ...(pool.selection !== 'enumeration' && resolved ? { poolTotal: total.toJSON() } : {}),
+        unresolved,
+    };
+}
+export function evaluateScopePools(scenario, definitions) {
+    return [...(scenario.scopePools ?? [])]
+        .sort((left, right) => compareCodeUnits(left.id, right.id))
+        .map((pool) => evaluatePool(scenario, pool, definitions));
+}

package/dist/hoi4_agent_tools/probability/simulation.js

@@ -1,3 +1,4 @@
+import { withScenarioPathValue } from './scenario-state.js';
 import { evaluateExactCandidates } from './evaluation.js';
 function recordUnresolved(unresolved, issue) {
     if (unresolved.some((existing) => existing.code === issue.code &&
@@ -222,7 +223,7 @@ function continuousSamples(scenario, samples, samplingMethod, random, unresolved
 }
 function sampledScenario(scenario, continuous, random, unresolved) {
     const inputs = scenario.uncertainInputs ?? [];
-    const state = { ...scenario.state };
+    let sampled = { ...scenario, state: { ...scenario.state } };
     for (const input of inputs) {
         let value;
         const plannedUniform = continuous.get(input.path);
@@ -244,9 +245,9 @@ function sampledScenario(scenario, continuous, random, unresolved) {
             });
         }
         else
-            state[input.path] = value;
+            sampled = withScenarioPathValue(sampled, input.path, value);
     }
-    return { ...scenario, state, uncertainInputs: [] };
+    return { ...sampled, uncertainInputs: [] };
 }
 function quantileForConfidence(confidence) {
     return inverseNormal(0.5 + confidence / 2);

package/dist/hoi4_agent_tools/probability/sweep.js

@@ -1,5 +1,6 @@
 import { ServiceError } from '../core/result.js';
 import { conditionBreakpointValues, evaluateSurfaceScenarios } from './evaluation.js';
+import { scenarioPathValue, withScenarioPathValue } from './scenario-state.js';
 const MAX_SWEEP_POINTS = 250_000;
 function declaredValues(surface, scenario, path, steps) {
     const uncertain = scenario.uncertainInputs?.find((input) => input.path === path);
@@ -15,7 +16,7 @@ function declaredValues(surface, scenario, path, steps) {
         if (values.length > 0)
             return [...new Set(values)].sort((left, right) => left - right);
     }
-    const current = scenario.state[path];
+    const current = scenarioPathValue(scenario, path);
     if (typeof current === 'number')
         return [current];
     throw new ServiceError('PROBABILITY_SWEEP_RANGE_REQUIRED', 'Every sweep path requires a scenario range, numeric alternatives, or numeric state value', { scenarioId: scenario.id, path });
@@ -26,7 +27,10 @@ function values(range, steps) {
     return Array.from({ length: steps }, (_, index) => range.min + ((range.max - range.min) * index) / (steps - 1));
 }
 function point(surface, scenario, definitions, path, value, assigned) {
-    const evaluated = evaluateSurfaceScenarios(surface, [{ ...scenario, state: { ...scenario.state, ...assigned }, uncertainInputs: [] }], definitions)[0];
+    const base = { ...scenario, uncertainInputs: [] };
+    const evaluated = evaluateSurfaceScenarios(surface, [
+        Object.entries(assigned).reduce((updated, [assignedPath, assignedValue]) => withScenarioPathValue(updated, assignedPath, assignedValue), base),
+    ], definitions)[0];
     return {
         scenarioId: scenario.id,
         path,