hoi4-agent-tools 3.1.0 → 3.3.0

package/dist/hoi4_agent_tools/schemas/scenarios.js

@@ -0,0 +1,264 @@
+import { z } from 'zod/v4';
+import { declaredConditionScenarioSchema } from './analysis.js';
+import { workspaceIdSchema, workspaceRelativePathSchema } from './common.js';
+const identifier = z.string().min(1).max(512);
+const manifestToken = z.string().regex(/^[A-Za-z0-9_.:-]{1,512}$/u);
+const sourceSelector = z
+    .object({
+    kind: z.enum(['scripted_effect', 'event_option', 'decision', 'focus_reward']),
+    id: identifier,
+    option: identifier.optional(),
+})
+    .strict();
+export const sharedScenarioSchema = declaredConditionScenarioSchema.safeExtend({
+    schemaVersion: z.literal('1.0'),
+    globalFlags: z.array(identifier).max(10_000).optional(),
+    scopeCatalogs: z
+        .record(identifier, z
+        .object({
+        complete: z.boolean(),
+        members: z.array(identifier).max(2_048),
+    })
+        .strict())
+        .optional(),
+});
+const assertionPath = z
+    .object({
+    scope: identifier.default('ROOT'),
+    key: identifier,
+})
+    .strict();
+const scalar = z.union([z.string().max(4_096), z.number(), z.boolean(), z.null()]);
+export const mechanicAssertionSchema = z.discriminatedUnion('kind', [
+    z
+        .object({ id: identifier, kind: z.literal('equals'), path: assertionPath, expected: scalar })
+        .strict(),
+    z
+        .object({
+        id: identifier,
+        kind: z.literal('conservation'),
+        paths: z.array(assertionPath).min(2).max(64),
+        tolerance: z.number().nonnegative().default(0),
+    })
+        .strict(),
+    z
+        .object({
+        id: identifier,
+        kind: z.literal('array_alignment'),
+        paths: z.array(assertionPath).min(2).max(32),
+    })
+        .strict(),
+    z
+        .object({
+        id: identifier,
+        kind: z.literal('affordability'),
+        balance: assertionPath,
+        cost: z.number().nonnegative(),
+    })
+        .strict(),
+    z
+        .object({
+        id: identifier,
+        kind: z.literal('single_payment'),
+        balance: assertionPath,
+        cost: z.number().nonnegative(),
+    })
+        .strict(),
+    z
+        .object({
+        id: identifier,
+        kind: z.literal('repeated_setup'),
+        firstStep: z.number().int().nonnegative(),
+        secondStep: z.number().int().nonnegative(),
+    })
+        .strict(),
+    z
+        .object({
+        id: identifier,
+        kind: z.literal('exclusive_flags'),
+        scope: identifier.default('ROOT'),
+        flags: z.array(identifier).min(2).max(64),
+    })
+        .strict(),
+    z
+        .object({
+        id: identifier,
+        kind: z.literal('cleanup'),
+        scope: identifier.default('ROOT'),
+        flags: z.array(identifier).max(64).default([]),
+        targets: z.array(identifier).max(64).default([]),
+    })
+        .strict(),
+    z
+        .object({ id: identifier, kind: z.literal('end_state'), path: assertionPath, expected: scalar })
+        .strict(),
+]);
+export const mechanicCaseSchema = z
+    .object({
+    id: identifier,
+    scenario: sharedScenarioSchema,
+    steps: z
+        .array(z.discriminatedUnion('kind', [
+        z
+            .object({
+            kind: z.literal('effect'),
+            source: sourceSelector,
+            repeat: z.number().int().min(1).max(8).default(1),
+        })
+            .strict(),
+        z
+            .object({ kind: z.literal('advance_days'), days: z.number().int().min(0).max(36_500) })
+            .strict(),
+    ]))
+        .min(1)
+        .max(128),
+    assertions: z.array(mechanicAssertionSchema).min(1).max(256),
+})
+    .strict();
+export const mechanicTestRequestSchema = z
+    .object({
+    workspaceId: workspaceIdSchema,
+    test: mechanicCaseSchema,
+    expectedRevision: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .optional(),
+    refresh: z.boolean().default(false),
+})
+    .strict();
+const manifestItem = z.object({ kind: manifestToken, id: manifestToken }).strict();
+export const packageManifestSchema = z
+    .object({
+    schemaVersion: z.literal('1.0'),
+    id: manifestToken,
+    definitions: z.array(manifestItem).max(2_048).default([]),
+    calls: z
+        .array(z.object({ from: manifestItem, to: manifestItem }).strict())
+        .max(2_048)
+        .default([]),
+    registrations: z
+        .array(z.object({ path: workspaceRelativePathSchema, token: manifestToken }).strict())
+        .max(2_048)
+        .default([]),
+    localisation: z.array(manifestToken).max(2_048).default([]),
+    assets: z.array(workspaceRelativePathSchema).max(2_048).default([]),
+    requiredCases: z
+        .array(z.object({ suite: workspaceRelativePathSchema, caseId: manifestToken }).strict())
+        .max(512)
+        .default([]),
+})
+    .strict();
+export const packageCheckRequestSchema = z
+    .object({
+    workspaceId: workspaceIdSchema,
+    manifest: packageManifestSchema,
+    expectedRevision: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .optional(),
+    refresh: z.boolean().default(false),
+})
+    .strict();
+const readOnlySuiteTool = z.enum([
+    'hoi4.impact_inspect',
+    'hoi4.decision_inspect',
+    'hoi4.event_inspect',
+    'hoi4.event_render',
+    'hoi4.tech_inspect',
+    'hoi4.tech_render',
+    'hoi4.probability_inspect',
+    'hoi4.probability_evaluate',
+    'hoi4.probability_render',
+    'hoi4.focus_inspect',
+    'hoi4.focus_render',
+    'hoi4.gui_inspect',
+    'hoi4.gui_render',
+    'hoi4.map_inspect',
+    'hoi4.map_render',
+]);
+const suiteCaseMetadata = {
+    sourceSelectors: z.array(manifestItem).max(64).default([]),
+    assertions: z
+        .array(z
+        .object({
+        id: identifier,
+        path: z.array(identifier).min(1).max(16),
+        expected: scalar,
+    })
+        .strict())
+        .max(64)
+        .default([]),
+    views: z
+        .array(z.enum(['summary', 'artifacts', 'diagnostics']))
+        .max(3)
+        .default(['summary']),
+};
+export const scenarioSuiteSchema = z
+    .object({
+    schemaVersion: z.literal('1.0'),
+    id: identifier,
+    cases: z
+        .array(z.discriminatedUnion('domain', [
+        z
+            .object({
+            domain: z.literal('mechanic'),
+            id: identifier,
+            test: mechanicCaseSchema,
+            ...suiteCaseMetadata,
+        })
+            .strict(),
+        z
+            .object({
+            domain: z.literal('package'),
+            id: identifier,
+            manifest: packageManifestSchema,
+            ...suiteCaseMetadata,
+        })
+            .strict(),
+        z
+            .object({
+            domain: z.literal('tool'),
+            id: identifier,
+            tool: readOnlySuiteTool,
+            arguments: z.record(z.string().max(256), z.json()),
+            ...suiteCaseMetadata,
+        })
+            .strict(),
+    ]))
+        .min(1)
+        .max(10_000),
+})
+    .strict()
+    .superRefine((suite, context) => {
+    const ids = new Set();
+    for (const [index, item] of suite.cases.entries()) {
+        if (ids.has(item.id))
+            context.addIssue({
+                code: 'custom',
+                path: ['cases', index, 'id'],
+                message: 'Suite case ids must be unique',
+            });
+        ids.add(item.id);
+    }
+});
+export const scenarioTestRequestSchema = z
+    .object({
+    workspaceId: workspaceIdSchema,
+    suite: scenarioSuiteSchema.optional(),
+    suitePath: workspaceRelativePathSchema.optional(),
+    continuation: z.string().max(4_096).optional(),
+    maxCases: z.number().int().min(1).max(256).default(32),
+    expectedRevision: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .optional(),
+    refresh: z.boolean().default(false),
+})
+    .strict()
+    .superRefine((input, context) => {
+    if ((input.suite === undefined) === (input.suitePath === undefined))
+        context.addIssue({
+            code: 'custom',
+            message: 'Specify exactly one inline suite or suitePath',
+        });
+});

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.3.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,8 @@
 
 - [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.
+- [Mechanic tests and scenario suites](mechanics.md): interpret declared effect steps, check package links, and run resumable cases.
 - [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/docs/mechanics.md

@@ -0,0 +1,70 @@
+# Mechanic tests, package checks, and scenario suites
+
+`hoi4.mechanic_test`, `hoi4.package_check`, and `hoi4.scenario_test` read authorized HOI4 source and return linked, revision-bound evidence.
+They do not launch the game or change source files.
+Supply `expectedRevision` when continuing analysis against a reviewed scan.
+
+## Test an effect
+
+`hoi4.mechanic_test` copies a versioned scenario, selects each active source effect, applies explicit steps, and evaluates typed assertions.
+Source selectors support `scripted_effect`, `event_option`, `decision`, and `focus_reward`; event options also need `option`.
+An `advance_days` step only expires modeled timed flags; it never runs on actions.
+
+```json
+{
+  "workspaceId": "current",
+  "test": {
+    "id": "treasury_transfer",
+    "scenario": {
+      "schemaVersion": "1.0",
+      "id": "treasury_transfer",
+      "state": { "treasury": 10, "savings": 2 },
+      "closedFlags": true
+    },
+    "steps": [{ "kind": "effect", "source": { "kind": "scripted_effect", "id": "transfer" } }],
+    "assertions": [
+      {
+        "id": "total_conserved",
+        "kind": "conservation",
+        "paths": [{ "key": "treasury" }, { "key": "savings" }]
+      },
+      {
+        "id": "single_charge",
+        "kind": "single_payment",
+        "balance": { "key": "treasury" },
+        "cost": 3
+      }
+    ]
+  }
+}
+```
+
+The linked trace records applied, skipped, and unresolved source operations with before and after values.
+The `single_payment` assertion checks the named balance's final change and the number and size of its traced deductions, so a compensating grant cannot hide a second charge.
+Supported operations include documented variable arithmetic, flags, event targets, arrays, conditionals, finite declared scope iteration, scripted helpers, safe meta substitutions, and selected balance effects.
+Decision engine political-power costs are applied once before `complete_effect`; custom cost triggers check affordability and their payment remains in `complete_effect`.
+Unresolved eligibility, unsupported effects, dynamic names that cannot be resolved, missing finite scope catalogs, and bounded-work limits remain unresolved rather than guessed.
+An effect with an unknown write set conservatively makes state assertions unresolved.
+This is source interpretation of declared steps, not campaign simulation.
+
+## Check a package
+
+`hoi4.package_check` accepts a declarative manifest with `schemaVersion: "1.0"` and an `id`.
+Add expected `definitions` and `calls` as `{ "kind": "scripted_effect", "id": "transfer" }` selectors, `registrations` as workspace-relative path and token pairs, `localisation` keys, `assets` as workspace-relative paths, and `requiredCases` as suite path and case id pairs.
+The report separates present, absent, shadowed, and unresolved links and includes source hashes and locations.
+Required cases are checked for declaration; run `hoi4.scenario_test` to evaluate them.
+The manifest accepts no source patches or executable commands.
+
+## Run a suite
+
+`hoi4.scenario_test` accepts either an inline `suite` or an authorized workspace-relative `suitePath`.
+The suite has `schemaVersion: "1.0"`, an `id`, and named `cases` in the `mechanic`, `package`, or fixed read-only `tool` domain.
+A mechanic case supplies the same `test` as `hoi4.mechanic_test`; a package case supplies a `manifest`.
+A tool case names one allowed inspect, render, or evaluate operation and supplies its typed `arguments`.
+Cases may declare `sourceSelectors`, output path assertions, and `views` (`summary`, `artifacts`, `diagnostics`).
+
+Set `maxCases` to bound a batch.
+Each case receives a content-addressed result artifact; the batch returns its counts and, while cases remain, a `continuation`.
+Pass that continuation with the same suite to resume.
+The token is authenticated and bound to the workspace, caller, suite content, and source revision; changed inputs or source require a fresh run.
+Every requested case is reported as completed, failed, unresolved, or pending.

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.3.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,8 @@
     "docs/README.md",
     "docs/setup.md",
     "docs/events.md",
+    "docs/analysis.md",
+    "docs/mechanics.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.3.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.3.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.3.0/schemas/custom-weighted-pool.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {