hoi4-agent-tools 3.1.0 → 3.2.0

package/dist/hoi4_agent_tools/schemas/analysis.js

@@ -0,0 +1,228 @@
+import { z } from 'zod/v4';
+import { workspaceIdSchema, workspaceRelativePathSchema } from './common.js';
+const symbolKindSchema = z.enum([
+    'focus_tree',
+    'focus',
+    'continuous_focus_palette',
+    'continuous_focus',
+    'decision',
+    'decision_category',
+    'event',
+    'idea',
+    'leader',
+    'formable',
+    'scripted_effect',
+    'scripted_trigger',
+    'script_constant',
+    'mtth_variable',
+    'ai_strategy',
+    'ai_strategy_plan',
+    'sprite',
+    'texture',
+    'gui_element',
+    'scripted_gui',
+    'technology',
+    'technology_folder',
+    'technology_category',
+    'technology_tag',
+    'equipment',
+    'equipment_module',
+    'sub_unit',
+    'unit_category',
+    'building',
+    'ability',
+    'combat_tactic',
+    'doctrine_folder',
+    'grand_doctrine',
+    'doctrine_track',
+    'subdoctrine',
+    'localisation',
+    'variable',
+    'flag',
+    'event_target',
+    'state',
+    'province',
+    'province_color',
+    'strategic_region',
+    'adjacency',
+    'supply_node',
+    'railway',
+]);
+export const impactSymbolSelectorSchema = z
+    .object({
+    kind: symbolKindSchema,
+    id: z.string().min(1).max(512),
+})
+    .strict();
+const sourceDisplayPathSchema = z
+    .string()
+    .min(1)
+    .max(4096)
+    .refine((value) => {
+    const separator = value.indexOf(':');
+    if (separator < 1)
+        return false;
+    const root = value.slice(0, separator);
+    if (!/^(?:mod|game|fixture|dependency-[0-9]+)$/u.test(root))
+        return false;
+    return workspaceRelativePathSchema.safeParse(value.slice(separator + 1)).success;
+}, 'Use a scanned source display path under an authorized workspace root');
+export const proposedAnalysisSourceSchema = z
+    .object({
+    relativePath: workspaceRelativePathSchema,
+    content: z
+        .string()
+        .max(8 * 1024 * 1024)
+        .nullable(),
+})
+    .strict();
+const scenarioScalarSchema = z.union([z.string().max(4096), z.number(), z.boolean(), z.null()]);
+const scenarioValueSchema = z.union([
+    scenarioScalarSchema,
+    z.array(scenarioScalarSchema).max(10_000),
+]);
+const scenarioStateSchema = z
+    .record(z.string().min(1).max(1024), scenarioValueSchema)
+    .refine((state) => Object.keys(state).length <= 10_000, 'Scenario state has too many keys');
+const scopeBindingSchema = 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: scenarioStateSchema,
+    flags: z.array(z.string().min(1).max(512)).max(10_000).optional(),
+    eventTargets: z.record(z.string().max(512), z.string().max(512)).optional(),
+    weight: z.union([z.number(), z.string().max(1024)]).optional(),
+})
+    .strict();
+export const declaredConditionScenarioSchema = z
+    .object({
+    id: z.string().min(1).max(512),
+    actor: z.string().max(256).optional(),
+    date: z.string().max(64).optional(),
+    state: scenarioStateSchema,
+    flags: z.array(z.string().min(1).max(512)).max(10_000).optional(),
+    eventTargets: z.record(z.string().max(512), z.string().max(512)).optional(),
+    scopes: z
+        .record(z.string().min(1).max(128), scopeBindingSchema)
+        .refine((scopes) => Object.keys(scopes).length <= 64, 'Too many declared scopes')
+        .optional(),
+    candidateOverrides: z.record(z.string().max(512), z.boolean()).optional(),
+    closedFlags: z.boolean().optional(),
+})
+    .strict();
+export const impactInspectRequestSchema = z
+    .object({
+    workspaceId: workspaceIdSchema,
+    symbols: z.array(impactSymbolSelectorSchema).max(64).default([]),
+    changedFiles: z.array(sourceDisplayPathSchema).max(64).default([]),
+    scenarioSuites: z
+        .array(workspaceRelativePathSchema.refine((value) => value.toLowerCase().endsWith('.json'), 'Scenario suite path must name a JSON file'))
+        .max(32)
+        .default([]),
+    proposedSources: z.array(proposedAnalysisSourceSchema).min(1).max(64).optional(),
+    maxNodes: z.number().int().min(1).max(50_000).optional(),
+    maxEdges: z.number().int().min(1).max(100_000).optional(),
+    maxDepth: z.number().int().min(1).max(64).optional(),
+    expectedRevision: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .optional(),
+    refresh: z.boolean().default(false),
+})
+    .strict()
+    .superRefine((input, context) => {
+    if (input.symbols.length === 0 &&
+        input.changedFiles.length === 0 &&
+        input.proposedSources === undefined)
+        context.addIssue({
+            code: 'custom',
+            message: 'Impact inspection requires a symbol, changed file, or proposed source',
+        });
+});
+export const decisionInspectRequestSchema = z
+    .object({
+    workspaceId: workspaceIdSchema,
+    mode: z.enum(['inventory', 'inspect', 'compare']).default('inventory'),
+    id: z.string().min(1).max(512).optional(),
+    scenarios: z.array(declaredConditionScenarioSchema).max(64).default([]),
+    proposedSources: z.array(proposedAnalysisSourceSchema).min(1).max(64).optional(),
+    expectedRevision: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .optional(),
+    refresh: z.boolean().default(false),
+})
+    .strict()
+    .superRefine((input, context) => {
+    const ids = new Set();
+    for (const [index, scenario] of input.scenarios.entries()) {
+        if (ids.has(scenario.id))
+            context.addIssue({
+                code: 'custom',
+                path: ['scenarios', index, 'id'],
+                message: 'Scenario IDs must be unique',
+            });
+        ids.add(scenario.id);
+    }
+    if (input.mode === 'inventory') {
+        if (input.proposedSources !== undefined)
+            context.addIssue({
+                code: 'custom',
+                path: ['proposedSources'],
+                message: 'Inventory mode does not accept proposed sources',
+            });
+        return;
+    }
+    if (input.id === undefined)
+        context.addIssue({
+            code: 'custom',
+            path: ['id'],
+            message: 'Decision inspection requires an identifier',
+        });
+    if (input.scenarios.length === 0)
+        context.addIssue({
+            code: 'custom',
+            path: ['scenarios'],
+            message: 'Decision inspection requires declared scenarios',
+        });
+    if (input.mode === 'compare' && input.proposedSources === undefined)
+        context.addIssue({
+            code: 'custom',
+            path: ['proposedSources'],
+            message: 'Decision comparison requires proposed sources',
+        });
+    if (input.mode === 'inspect' && input.proposedSources !== undefined)
+        context.addIssue({
+            code: 'custom',
+            path: ['proposedSources'],
+            message: 'Use compare mode for proposed sources',
+        });
+});
+/** A reference projection of future scenario suites; Stage 3 reads but never executes it. */
+export const impactScenarioSuiteReferenceSchema = z
+    .object({
+    schemaVersion: z.literal('1.0'),
+    id: z.string().min(1).max(512),
+    cases: z
+        .array(z
+        .object({
+        id: z.string().min(1).max(512),
+        sourceSelectors: z.array(impactSymbolSelectorSchema).max(64).default([]),
+        sourceFiles: z.array(sourceDisplayPathSchema).max(64).default([]),
+    })
+        .loose())
+        .max(1_000),
+})
+    .loose();

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

package/docs/README.md

@@ -2,6 +2,7 @@
 
 - [Setup](setup.md): install the server, configure HOI4 paths, and connect an MCP client.
 - [Event chains](events.md): inspect, trace, lint, render, and compare event chains.
+- [Cross-system impact and decisions](analysis.md): trace source consumers and evaluate decision or mission scenarios.
 - [Technology trees](technology.md): inspect, trace, lint, render, and compare technologies and doctrines.
 - [Bounded helper expansion](helper-expansion.md): resume source-linked event and technology helper paths with exact coverage boundaries.
 - [Persistent jobs](jobs.md): run, inspect, cancel, and recover long operations.

package/docs/analysis.md

@@ -0,0 +1,100 @@
+# Cross-system impact and decisions
+
+`hoi4.impact_inspect` and `hoi4.decision_inspect` analyze authorized HOI4 source without changing it or running the game.
+Both tools return a compact result and a linked JSON report containing source locations, hashes, unresolved cases, and the full analysis.
+They support ordinary calls and persistent MCP tasks through stdio and HTTP.
+
+## Cross-system impact
+
+Use a symbol when you know the definition you plan to change:
+
+```json
+{
+  "workspaceId": "current",
+  "symbols": [{ "kind": "idea", "id": "rationing" }],
+  "maxDepth": 12
+}
+```
+
+Use `changedFiles` with scanned display paths such as `mod:common/ideas/rationing.txt` to seed every active definition in a file.
+Use `proposedSources` to add, replace, or remove files in memory under the authorized mod root; a `null` content removes a source from the proposed snapshot.
+When `changedFiles` is omitted, each proposed file seeds all its active definitions alongside any selected symbols.
+The report compares the original and proposed consumer graph, including added and removed consumers and affected files.
+Moving a source location within one file does not count an unchanged reference as a new or removed consumer.
+`expectedRevision` prevents analysis against a source revision different from the one the caller reviewed.
+Pass up to 32 workspace-relative JSON paths in `scenarioSuites` to locate cases that declare an affected source selector or scanned display path.
+The tool reads reference metadata only; it never runs a case or its assertions.
+
+```json
+{
+  "schemaVersion": "1.0",
+  "id": "policy_checks",
+  "cases": [
+    {
+      "id": "rationing_decision",
+      "sourceSelectors": [{ "kind": "decision", "id": "ration" }],
+      "sourceFiles": ["mod:common/decisions/rationing.txt"]
+    }
+  ]
+}
+```
+
+The suite can carry additional case fields for a later scenario executor; impact analysis reads only `sourceSelectors` and `sourceFiles`.
+Malformed, missing, or oversized suite files produce explicit partial coverage.
+
+The graph includes active and overridden definitions, direct and transitive consumers, source locations, state-key reads and writes, and coverage limits.
+It connects source-backed event, focus, decision, idea, technology, scripted-helper, localisation, GUI, sprite, and texture references where a typed static edge can be established.
+Unresolved dynamic names, missing definitions, skipped sources, cycles, and traversal limits remain explicit in the report.
+An affected file is a source dependency lead, not a claim that the game executed that path.
+
+## Decisions and missions
+
+Inventory active decision categories and definitions:
+
+```json
+{ "workspaceId": "current", "mode": "inventory" }
+```
+
+Inspect one decision under declared actor and target state:
+
+```json
+{
+  "workspaceId": "current",
+  "mode": "inspect",
+  "id": "fund_relief",
+  "scenarios": [
+    {
+      "id": "actor_and_target",
+      "actor": "AAA",
+      "state": { "political_power": 30, "treasury": 20 },
+      "flags": ["relief_open"],
+      "scopes": {
+        "FROM": {
+          "id": "BBB",
+          "type": "country",
+          "actor": "BBB",
+          "state": {}
+        }
+      }
+    }
+  ]
+}
+```
+
+`ROOT` is the actor country and `FROM` is the declared target country or state.
+The inventory lists active decisions, category fragments, overridden source definitions, and each decision's explicit targets, target arrays, state filters, and target trigger declarations.
+Category and decision `allowed`, `visible`, and `available` results remain separate; mission visibility is reported as ignored where documented.
+Target selection covers explicit lists and arrays plus supported state ownership, control, and continent filters.
+When a target, flag, variable, or helper input is unknown, the corresponding gate remains unresolved.
+
+Costs distinguish automatic engine political-power payment from a custom affordability trigger and its separate `complete_effect` payment.
+The report identifies direct deductions, possible double payment, missing direct payment, conditional or helper-dependent paths, repeatability, cooldowns, removal, activation, cancellation, and mission timeout paths.
+Removal and cancellation triggers are evaluated under each declared scenario; `cancel_if_not_visible` is evaluated against decision visibility, with unsupported mission visibility left unresolved.
+It does not execute these effects or assert that a campaign reached an outcome.
+
+Set `mode` to `compare` and supply `proposedSources` to compare the same scenarios against an in-memory source proposal.
+Decision AI scores use the existing probability service's `decision_ai_will_do` and `mission_ai_will_do` adapters, with linked score traces and unresolved input evidence.
+Those adapters return scores and eligibility; they do not invent selection probabilities.
+When a proposal changes multiple files or adds or removes the weighted definition, the report marks proposed AI scoring unresolved and points to explicit probability comparison.
+
+All paths and scenarios are bounded by the public input schema, and artifacts remain subject to workspace and principal authorization.

package/docs/jobs.md

@@ -14,9 +14,10 @@ A modern native task handoff ends that request's heartbeat without declaring the
 
 ## Supported tools
 
-Optional tasks are available for every read-only event, technology, probability, map, GUI, and focus operation, and for the three rewrite tools:
+Optional tasks are available for every read-only event, impact, decision, technology, probability, map, GUI, and focus operation, and for the three rewrite tools:
 
 - `hoi4.event_inspect`, `hoi4.event_render`, and `hoi4.event_compare`
+- `hoi4.impact_inspect` and `hoi4.decision_inspect`
 - `hoi4.tech_inspect`, `hoi4.tech_render`, and `hoi4.tech_compare`
 - `hoi4.probability_inspect`, `hoi4.probability_evaluate`, `hoi4.probability_sweep`, `hoi4.probability_simulate`, `hoi4.probability_sequence`, `hoi4.probability_compare`, and `hoi4.probability_render`
 - `hoi4.map_inspect`, `hoi4.map_render`, and `hoi4.map_rewrite`

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "hoi4-agent-tools",
   "mcpName": "io.github.klimPaskov/hoi4-agent-tools",
-  "version": "3.1.0",
-  "description": "Analyze HOI4 events, tech trees, AI weights, and MTTH; build focus trees, GUIs, and maps.",
+  "version": "3.2.0",
+  "description": "Analyze HOI4 events, decisions, impact, tech, AI, and MTTH; build focus trees, GUIs, and maps.",
   "type": "module",
   "license": "Apache-2.0",
   "author": "HOI4 Agent Tools contributors",
@@ -22,6 +22,8 @@
     "clausewitz",
     "focus-trees",
     "event-chains",
+    "impact-analysis",
+    "decisions",
     "technology-trees",
     "doctrines",
     "ai-weights",
@@ -39,6 +41,7 @@
     "docs/README.md",
     "docs/setup.md",
     "docs/events.md",
+    "docs/analysis.md",
     "docs/technology.md",
     "docs/probability.md",
     "docs/research/probability-adapter-evidence.md",

package/schemas/configuration.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.1.0/schemas/configuration.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.2.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/v3.1.0/schemas/continuous-focus-palette.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.2.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/v3.1.0/schemas/custom-weighted-pool.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.2.0/schemas/custom-weighted-pool.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {