hoi4-agent-tools 2.6.0 → 2.8.0

package/dist/hoi4_agent_tools/schemas/probability.js

@@ -82,6 +82,62 @@ const uncertainInputSchema = z
             message: 'Range min must not exceed max',
         });
 });
+const probabilityScopeBindingSchema = z
+    .object({
+    id: z.string().min(1).max(512),
+    type: z
+        .enum([
+        'country',
+        'state',
+        'character',
+        'unit_leader',
+        'operative',
+        'strategic_region',
+        'province',
+        'unknown',
+    ])
+        .optional(),
+    actor: z.string().max(256).optional(),
+    state: z.record(z.string().min(1).max(1024), scenarioValueSchema).default({}),
+    flags: z.array(z.string().min(1).max(512)).max(100_000).optional(),
+    eventTargets: z.record(z.string().max(512), z.string().max(512)).optional(),
+    weight: z.union([z.number().nonnegative(), z.string().min(1).max(1024)]).optional(),
+})
+    .strict();
+const probabilityScopePoolSchema = z
+    .object({
+    id: z.string().min(1).max(512),
+    bindAs: z.string().min(1).max(512).default('THIS'),
+    selection: z
+        .enum(['enumeration', 'uniform', 'proportional_categorical'])
+        .default('enumeration'),
+    complete: z.boolean().default(false),
+    filter: z
+        .object({
+        inlineClausewitz: z.string().min(1).max(1_048_576).optional(),
+        scriptedTrigger: z.string().min(1).max(512).optional(),
+    })
+        .strict()
+        .superRefine((filter, context) => {
+        if ((filter.inlineClausewitz === undefined) === (filter.scriptedTrigger === undefined))
+            context.addIssue({
+                code: 'custom',
+                message: 'Scope-pool filter requires exactly one inlineClausewitz or scriptedTrigger',
+            });
+    })
+        .optional(),
+    candidates: z.array(probabilityScopeBindingSchema).min(1).max(100_000),
+})
+    .strict()
+    .superRefine((pool, context) => {
+    const ids = pool.candidates.map(({ id }) => id);
+    if (new Set(ids).size !== ids.length)
+        context.addIssue({
+            code: 'custom',
+            path: ['candidates'],
+            message: 'Scope-pool candidate IDs must be unique',
+        });
+});
 export const probabilityScenarioSchema = z
     .object({
     id: z.string().min(1).max(512),
@@ -92,6 +148,8 @@ export const probabilityScenarioSchema = z
     state: z.record(z.string().min(1).max(1024), scenarioValueSchema),
     flags: z.array(z.string().min(1).max(512)).max(100_000).optional(),
     eventTargets: z.record(z.string().max(512), z.string().max(512)).optional(),
+    scopes: z.record(z.string().min(1).max(512), probabilityScopeBindingSchema).optional(),
+    scopePools: z.array(probabilityScopePoolSchema).max(100_000).optional(),
     candidateOverrides: z.record(z.string().max(512), z.boolean()).optional(),
     uncertainInputs: z.array(uncertainInputSchema).max(10_000).optional(),
     correlations: z
@@ -118,6 +176,13 @@ export const probabilityScenarioSchema = z
 })
     .strict()
     .superRefine((scenario, context) => {
+    const poolIds = scenario.scopePools?.map(({ id }) => id) ?? [];
+    if (new Set(poolIds).size !== poolIds.length)
+        context.addIssue({
+            code: 'custom',
+            path: ['scopePools'],
+            message: 'Scope-pool IDs must be unique within a scenario',
+        });
     const paths = scenario.uncertainInputs?.map(({ path }) => path) ?? [];
     if (new Set(paths).size !== paths.length)
         context.addIssue({
@@ -596,6 +661,30 @@ const candidateAnalysisSchema = z
     unresolved: z.array(probabilityUnresolvedSchema),
 })
     .strict();
+const scopePoolCandidateAnalysisSchema = z
+    .object({
+    id: z.string(),
+    eligibility: z.enum(['true', 'false', 'unresolved']),
+    weight: rationalJsonSchema.optional(),
+    conditionalProbability: z.number().min(0).max(1).optional(),
+    exactConditionalProbability: rationalJsonSchema.optional(),
+    trace: z.array(valueTraceSchema),
+    unresolved: z.array(probabilityUnresolvedSchema),
+})
+    .strict();
+const scopePoolAnalysisSchema = z
+    .object({
+    id: z.string(),
+    bindAs: z.string(),
+    selection: z.enum(['enumeration', 'uniform', 'proportional_categorical']),
+    poolComplete: z.boolean(),
+    candidates: z.array(scopePoolCandidateAnalysisSchema),
+    eligibleCandidateIds: z.array(z.string()),
+    unresolvedCandidateIds: z.array(z.string()),
+    poolTotal: rationalJsonSchema.optional(),
+    unresolved: z.array(probabilityUnresolvedSchema),
+})
+    .strict();
 const scenarioAnalysisSchema = z
     .object({
     id: z.string(),
@@ -623,6 +712,7 @@ const scenarioAnalysisSchema = z
     })
         .strict())
         .optional(),
+    scopePools: z.array(scopePoolAnalysisSchema).optional(),
     summary: z
         .object({
         topOutcomes: z.array(z.string()),

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.6.0';
+export const PACKAGE_VERSION = '2.8.0';
 export const MCP_PROTOCOL_VERSION = LATEST_PROTOCOL_VERSION;
 export const CONFIG_VERSION = 1;
 export const TRANSACTION_VERSION = 1;

package/docs/gui.md

@@ -31,6 +31,10 @@ Rewrite once, then inspect and render the result.
 
 Inspection checks missing assets and localisation, invalid sizes, overlap, clipping, overflow, button-label centering, content crossing a background boundary, conflicting click regions, invisible blockers, broken parents or contexts, list-row cuts, state conflicts, trigger/effect gaps, and resolution drift. `hoi4.gui_render` returns a scripted-scenario gallery and JSON delta report alongside the generic state and resolution galleries.
 
+The renderer resolves sprites and fonts through the complete mod, dependency, and installed-game load order. Mod windows therefore render ordinary vanilla sprites, tiled vanilla panels, progress bars, masked shields, button frames, and localisation icons such as `£command_power` without copying game assets into the mod. Case differences in GFX and font identifiers do not prevent a valid asset from resolving.
+
+Layout follows Clausewitz orientation and element-origin anchors, including `CENTER_LEFT`, `CENTER_RIGHT`, `CENTER_UP`, `CENTER_DOWN`, `origo`, `centerposition`, inherited container coordinate origins, local scale, and both `%` and `%%` relative dimensions. Text boxes use native font metrics together with `maxWidth`, `maxHeight`, alignment, wrapping, and `fixedsize` clipping. Cornered tile sprites use fixed nine-slice borders and optional center tiling; progress bars composite their filled and background textures; masked shields composite their background and mask textures.
+
 Preview scenarios can include exact layout expectations:
 
 ```json
@@ -60,4 +64,4 @@ The renderer does not run the game engine. Each render includes a fidelity repor
 
 Unresolved numeric runtime values such as `[?variable|format]` render as `[X]`. Unresolved text-returning scripted or scoped localisation such as `[GetStatusText]`, `[FROM.GetName]`, and `[?leader_scope.GetName]` renders as `[dynamic_loc]`. Provide scenario values when the exact value matters. Supported HOI4 `§` localisation colour controls are applied to preview text and `§!` restores the default colour.
 
-A rewrite stops if malformed or unsupported GUI script makes the requested change ambiguous. Runtime animation, masking, tiling, hardcoded controls, and dynamic values may require exact game precedents even when a useful offline preview is available.
+A rewrite stops if malformed or unsupported GUI script makes the requested change ambiguous. Frame-sheet animation, nine-slice tiling, progress composition, masking, and the primary and secondary textures referenced by vanilla GFX definitions render offline. Engine shader programs, hardcoded controls, and dynamic values that are not supplied by a scenario remain fidelity-report entries; an unexecuted shader never hides its resolved base texture.

package/docs/probability.md

@@ -42,6 +42,50 @@ A scenario contains only state the caller is willing to declare. Missing values
 }
 ```
 
+Use `scopes` to bind exact Clausewitz scope expressions. A binding carries its own actor, state, flags, and event targets, so a `FROM` trigger is evaluated against `FROM` rather than the root country. Chained names such as `FROM.FROM`, plus `ROOT`, `THIS`, `PREV`, `scope:name`, and `event_target:name`, are resolved without replacing their inner conditions with a single boolean. Scoped numeric expressions such as `FROM.variable_name` and uncertain paths such as `scopes.FROM.variable.variable_name` use the same binding.
+
+Use `scopePools` when source logic builds a destination, target, opposition, donor, or other runtime candidate set. Each pool supplies a candidate catalog, the scope alias to bind, and either an inline trigger filter or a named scripted trigger. The result enumerates every eligible, excluded, and unresolved candidate. `uniform` and `proportional_categorical` pools also return exact shares when `complete` is true; an incomplete catalog is still enumerated but is not normalized.
+
+```json
+{
+  "id": "relief_routes",
+  "state": {},
+  "scopes": {
+    "FROM": {
+      "id": "origin",
+      "type": "country",
+      "actor": "FRA",
+      "state": { "variable.relief_pressure": 7 }
+    }
+  },
+  "scopePools": [
+    {
+      "id": "relief_donor",
+      "bindAs": "FROM",
+      "selection": "proportional_categorical",
+      "complete": true,
+      "filter": {
+        "inlineClausewitz": "FROM = { check_variable = { var = relief_ready value = 1 compare = greater_than_or_equals } }"
+      },
+      "candidates": [
+        {
+          "id": "GER",
+          "actor": "GER",
+          "state": { "variable.relief_ready": 1, "variable.donor_weight": 1 },
+          "weight": "FROM.donor_weight"
+        },
+        {
+          "id": "ITA",
+          "actor": "ITA",
+          "state": { "variable.relief_ready": 1, "variable.donor_weight": 3 },
+          "weight": "FROM.donor_weight"
+        }
+      ]
+    }
+  ]
+}
+```
+
 Focus, technology, and doctrine probabilities require a complete candidate pool. Their engine rule is an independent uniform score race, not weight divided by total weight. Focus scenarios use `focus.external_factors_complete: true` only after the caller has supplied every relevant prerequisite and strategy factor. Technology and doctrine scenarios use `technology.external_factors_complete: true` only after cost, date, bonus, strategy, and candidate effects are accounted for.
 
 Decision and mission adapters intentionally return scores and ranks without inventing normalized probabilities. Event-option and `random_list` adapters normalize only their complete local pools. Direct random remains an independent percentage. MTTH horizon chance uses the versioned game timing model and returns a bound when an inactive-to-active polling phase is unknown.
@@ -61,6 +105,8 @@ Authoritative JSON keeps these fields separate:
 
 Every candidate includes source provenance with a stable AST path, an ordered modifier trace, support level, and unresolved analysis. `external` support means the parsed candidate is valid but its surrounding game factors were not fully declared. The tool response stays compact; complete matrices, traces, simulations, comparisons, and visuals are linked MCP resources.
 
+Every evaluated scope pool is stored with the scenario in authoritative JSON. Pool rows include eligibility, resolved weight, exact conditional share when supported, trigger traces, eligible IDs, unresolved IDs, and unresolved evidence. Compact MCP responses report pool and pool-candidate counts without copying the full catalog into the prompt.
+
 Nested `random_list` entries report both their conditional share inside the immediate list and their full path probability through every enclosing list. Dynamic parent paths remain explicit unresolved evidence.
 
 Deterministic simulation uses constant-memory Latin hypercube sampling by default, with seeded pseudo-random sampling available when requested. Numeric distributions can use a Gaussian copula correlation matrix. Discrete or categorical correlation requests are sampled independently and reported as unresolved instead of being approximated silently. Simulation reports Wilson intervals, effective sample count, global input importance, and HOI4 daily-hazard MTTH samples. Timing quantiles use a deterministic bounded reservoir and include their confidence basis and retained sample count.

package/docs/research/probability-adapter-evidence.md

@@ -55,7 +55,8 @@ When a game root is configured, adapter execution verifies `launcher-settings.js
 The analyzer reports, but does not guess or execute:
 
 - arbitrary effects used to calculate later weights;
-- unprovided scopes, event targets, game rules, DLC state, dynamic identifiers, meta effects, or scripted-localisation results;
+- scope chains, event targets, game rules, DLC state, dynamic identifiers, meta effects, or scripted-localisation results that are neither present in source nor declared through structured scenario bindings;
+- runtime scope pools whose candidate catalog is not declared; declared catalogs are filtered and enumerated exactly, while normalized shares additionally require explicit completeness;
 - parameterized scripted triggers whose arguments cannot be resolved from the selected source;
 - recursive MTTH variables or helper cycles;
 - incomplete focus, technology, doctrine, event-option, or random-list candidate pools;

package/examples/probability/scoped-dynamic-pools-evaluate-input.json

@@ -0,0 +1,50 @@
+{
+  "adapter": "event_option_ai_chance",
+  "source": {
+    "inlineClausewitz": "country_event = { id = scoped.1 option = { name = scoped.1.a ai_chance = { base = 1 modifier = { factor = 3 FROM = { tag = FRA } } } } option = { name = scoped.1.b ai_chance = { base = 1 } } }"
+  },
+  "scenarioSet": {
+    "schemaVersion": "1.0",
+    "id": "scoped_dynamic_pools",
+    "scenarios": [
+      {
+        "id": "france_origin",
+        "state": {},
+        "scopes": {
+          "FROM": {
+            "id": "origin",
+            "type": "country",
+            "actor": "FRA",
+            "state": {}
+          }
+        },
+        "scopePools": [
+          {
+            "id": "destination",
+            "bindAs": "FROM",
+            "selection": "uniform",
+            "complete": true,
+            "filter": {
+              "inlineClausewitz": "FROM = { is_ai = yes }"
+            },
+            "candidates": [
+              {
+                "id": "GER",
+                "type": "country",
+                "actor": "GER",
+                "state": { "is_ai": true }
+              },
+              {
+                "id": "ITA",
+                "type": "country",
+                "actor": "ITA",
+                "state": { "is_ai": true }
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  },
+  "outputs": ["json", "unresolved"]
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hoi4-agent-tools",
   "mcpName": "io.github.klimPaskov/hoi4-agent-tools",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "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.6.0/schemas/configuration.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.0/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.6.0/schemas/continuous-focus-palette.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.0/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.6.0/schemas/custom-weighted-pool.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.0/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.6.0/schemas/event-feature-manifest.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.0/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.6.0/schemas/focus-plan.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.0/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.6.0/schemas/focus-planning-sidecar.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.0/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.6.0/schemas/gui-animation-source.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.0/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.6.0/schemas/gui-helper.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.0/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.6.0/schemas/gui-scenario.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.0/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.6.0/schemas/map-operation.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.0/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.6.0/schemas/operation-result.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.0/schemas/operation-result.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {