hoi4-agent-tools 1.1.0 → 2.0.0

package/dist/hoi4_agent_tools/schemas/common.js

@@ -1,5 +1,9 @@
 import { z } from 'zod/v4';
-export const workspaceIdSchema = z.string().regex(/^[a-z][a-z0-9_-]{0,63}$/u);
+/** Optional for local agents: omitted means the mod containing the MCP cwd. */
+export const workspaceIdSchema = z
+    .string()
+    .regex(/^[a-z][a-z0-9_-]{0,63}$/u)
+    .default('current');
 const diagnosticCodeSchema = z.string().min(1).max(256);
 const diagnosticMessageSchema = z.string().max(4096);
 const sourceDisplayPathSchema = z.string().min(1).max(4096);

package/dist/hoi4_agent_tools/schemas/event.js

@@ -0,0 +1,95 @@
+import { z } from 'zod/v4';
+import { SOURCE_MAX_BYTES } from '../core/source/index.js';
+import { workspaceRelativePathSchema } from './common.js';
+const eventIdSchema = z.string().min(1).max(256);
+const eventSourcePathSchema = z.string().min(1).max(1024);
+const eventNodeIdSchema = z.string().min(1).max(1024);
+const eventSha256Schema = z.string().regex(/^[a-f0-9]{64}$/u);
+export const eventInspectModeSchema = z.enum([
+    'scan',
+    'roots',
+    'trace',
+    'explain_path',
+    'state_flow',
+    'lint',
+    'impact',
+]);
+export const eventDirectionSchema = z.enum(['upstream', 'downstream', 'both']);
+export const eventRenderViewSchema = z.enum([
+    'overview',
+    'neighborhood',
+    'options',
+    'entries',
+    'reachability',
+    'timing',
+    'state',
+    'targets',
+    'scope',
+    'terminals',
+    'unresolved',
+]);
+export const eventFeatureManifestSchema = z
+    .object({
+    id: z.string().min(1).max(128).optional(),
+    eventIds: z.array(eventIdSchema).max(2_000).optional(),
+    namespaces: z.array(z.string().min(1).max(256)).max(500).optional(),
+    sourcePaths: z.array(eventSourcePathSchema).max(2_000).optional(),
+    nodeIds: z.array(eventNodeIdSchema).max(5_000).optional(),
+})
+    .strict();
+export const eventSelectorSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('event'), eventId: eventIdSchema }).strict(),
+    z.object({ kind: z.literal('namespace'), namespace: z.string().min(1).max(256) }).strict(),
+    z.object({ kind: z.literal('file'), sourcePath: eventSourcePathSchema }).strict(),
+    z
+        .object({
+        kind: z.literal('source'),
+        sourcePath: eventSourcePathSchema,
+        line: z.number().int().positive(),
+        column: z.number().int().positive().optional(),
+    })
+        .strict(),
+    z.object({ kind: z.literal('node'), nodeId: eventNodeIdSchema }).strict(),
+    z.object({ kind: z.literal('manifest'), manifest: eventFeatureManifestSchema }).strict(),
+]);
+export const eventStateSubjectSchema = z
+    .object({
+    kind: z.enum([
+        'country_flag',
+        'global_flag',
+        'state_flag',
+        'variable',
+        'global_variable',
+        'array',
+        'event_target',
+        'global_event_target',
+        'saved_scope',
+    ]),
+    name: z.string().min(1).max(512),
+})
+    .strict();
+export const eventImpactSubjectSchema = z
+    .object({
+    kind: z.enum(['event', 'helper', 'flag', 'variable', 'array', 'event_target', 'saved_scope']),
+    name: z.string().min(1).max(512),
+})
+    .strict();
+export const eventGraphReferenceSchema = z
+    .object({
+    revision: eventSha256Schema.optional(),
+    artifactUri: z
+        .string()
+        .min(1)
+        .max(8_192)
+        .regex(/^hoi4-agent:\/\//u)
+        .optional(),
+})
+    .strict()
+    .refine(({ revision, artifactUri }) => Number(revision !== undefined) + Number(artifactUri !== undefined) === 1, 'Provide exactly one event graph revision or artifact URI');
+export const eventProposedSourceSchema = z
+    .object({
+    relativePath: workspaceRelativePathSchema,
+    source: z.string().max(SOURCE_MAX_BYTES).nullable(),
+    expectedSourceHash: eventSha256Schema.optional(),
+})
+    .strict();

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

package/docs/README.md

@@ -1,6 +1,7 @@
 # Documentation
 
 - [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.
 - [Focus trees](focus.md): inspect, create, render, and clean national or continuous focus content.
 - [Scripted GUIs](gui.md): inspect linked UI source, render states, and create or repair GUIs.
 - [Maps](map.md): inspect and edit provinces, states, regions, adjacency, supply, and railways.

package/docs/development.md

@@ -19,4 +19,14 @@ npm run inspector
 
 Keep changes focused and include tests for behavior changes. CI fixtures must be synthetic and project-owned; never commit installed-game or third-party-mod content. Public tool or schema changes require compatibility review and a versioned release.
 
+The event-chain acceptance fixture contains more than 300 project-owned event definitions and exercises routes, options, timing, state flow, scope changes, unresolved dynamic calls, rendering, and comparison. Local opt-in tests can also read an installed game and an external mod without copying their sources:
+
+```bash
+HOI4_GAME_ROOT="/games/Hearts of Iron IV" \
+HOI4_EXTERNAL_MOD_ROOT="/projects/hoi4-mod" \
+npm run test:local
+```
+
+Add `HOI4_DEPENDENCY_ROOTS` as the platform path-delimited list when the external mod has dependencies. Local tests remain read-only.
+
 See the package [Security Policy](../SECURITY.md) for private vulnerability reporting.

package/docs/events.md

@@ -0,0 +1,113 @@
+# Event chains
+
+The Event Chain Viewer analyzes event definitions and call sites across the active mod, configured dependencies, and vanilla sources. It is read-only: it does not rewrite event files or simulate the game.
+
+Use the three event tools directly; omit `workspaceId` when the MCP working directory is inside the target mod.
+
+## Inspect
+
+`hoi4.event_inspect` provides seven focused modes:
+
+- `scan`: inventory event definitions, namespaces, call sites, and unresolved references.
+- `roots`: find likely entry points and explain why they are roots.
+- `trace`: follow bounded incoming or outgoing routes from an event.
+- `explain_path`: explain a selected route edge by edge with exact source locations.
+- `state_flow`: report flags, variables, targets, scopes, and other tracked state read or changed along a route.
+- `lint`: find missing targets, unreachable events, suspicious cycles, conflicting definitions, invalid timing, and unresolved dynamic calls.
+- `impact`: identify callers, descendants, state dependencies, and files affected by a proposed event change.
+
+Use narrow identifiers, direction, and depth limits when the task concerns one chain. The compact response summarizes the result; complete graphs and diagnostics are returned as linked resources.
+
+Selectors use one of these forms:
+
+```json
+{ "kind": "event", "eventId": "namespace.1" }
+{ "kind": "namespace", "namespace": "namespace" }
+{ "kind": "file", "sourcePath": "events/example.txt" }
+{ "kind": "source", "sourcePath": "events/example.txt", "line": 40 }
+{ "kind": "node", "nodeId": "event:namespace.1" }
+{ "kind": "manifest", "manifest": { "eventIds": ["namespace.1", "namespace.2"] } }
+```
+
+`trace` uses `selector`; `explain_path` uses `from` and `to`; and `state_flow` may add a `stateSubject` object with `kind` and `name`. Allowed state kinds are `country_flag`, `global_flag`, `state_flag`, `variable`, `global_variable`, `array`, `event_target`, `global_event_target`, and `saved_scope`.
+
+`impact` requires an `impactSubject` object with `kind` and `name`. Allowed impact kinds are `event`, `helper`, `flag`, `variable`, `array`, `event_target`, and `saved_scope`. Set `refresh: true` after source changes when a prior graph may be cached.
+
+Example `hoi4.event_inspect` arguments:
+
+```json
+{
+  "workspaceId": "my-mod",
+  "mode": "trace",
+  "selector": { "kind": "event", "eventId": "namespace.1" },
+  "direction": "downstream",
+  "maxDepth": 8,
+  "maxNodes": 500,
+  "maxEdges": 2000,
+  "expandHelpers": false,
+  "refresh": false
+}
+```
+
+## Render
+
+`hoi4.event_render` produces deterministic, source-linked views of a chain. The exact `view` values are `overview`, `neighborhood`, `options`, `entries`, `reachability`, `timing`, `state`, `targets`, `scope`, `terminals`, and `unresolved`. JSON is the authoritative graph; SVG and PNG provide visual review, with HTML available for bundled navigation when requested.
+
+Large overview requests return a compact overview plus bounded branch JSON/SVG/PNG resources and a coverage manifest. The manifest indexes every generated data artifact by canonical MCP resource URI, including artifacts omitted from the compact tool response. Follow those links instead of asking the agent to reason from one unreadable all-node image.
+
+Dynamic and meta-generated targets that cannot be resolved statically remain explicit unresolved edges. The renderer never invents a destination.
+
+Example `hoi4.event_render` arguments:
+
+```json
+{
+  "workspaceId": "my-mod",
+  "view": "neighborhood",
+  "selector": { "kind": "event", "eventId": "namespace.1" },
+  "direction": "both",
+  "maxDepth": 4,
+  "maxNodes": 120,
+  "expandHelpers": false,
+  "includeHtml": false,
+  "refresh": false
+}
+```
+
+## Compare
+
+`hoi4.event_compare` compares whole workspace event graphs; it does not accept a chain selector. `before` and `after` each accept exactly one graph reference: `{ "revision": "<sha256>" }` or `{ "artifactUri": "hoi4-agent://..." }`. If no reference or overlay is supplied, the tool compares the previous cached revision with a fresh scan of the current source and reports an error when no prior revision is available. Comparisons refresh current source by default so normal agent file edits are detected; set `refresh: false` only when intentionally comparing cached graphs.
+
+Alternatively, compare the current graph with `proposedSources`, an in-memory list of `{ relativePath, source, expectedSourceHash? }` overlays. Set `source` to a string to add or replace source, or to `null` to delete an existing mod source. `after` and `proposedSources` are mutually exclusive. Proposed sources are analyzed without being written. The result reports added, removed, and changed definitions, edges, options, state operations, diagnostics, and route reachability.
+
+Example `hoi4.event_compare` arguments:
+
+```json
+{
+  "workspaceId": "my-mod",
+  "proposedSources": [
+    {
+      "relativePath": "events/example.txt",
+      "source": "add_namespace = namespace\ncountry_event = { id = namespace.1 }\n"
+    },
+    {
+      "relativePath": "events/obsolete.txt",
+      "source": null
+    }
+  ],
+  "render": true,
+  "maxRenderNodes": 120,
+  "refresh": true
+}
+```
+
+## Agent workflow
+
+A coding agent can combine the viewer with repository instructions, skills, and other tools:
+
+1. call `hoi4.event_inspect` with `scan` or `roots` to locate the chain;
+2. use `trace`, `explain_path`, `state_flow`, or `impact` for the current task;
+3. read linked JSON evidence only when the compact summary is insufficient;
+4. edit event source with the agent's normal file-editing workflow;
+5. call `hoi4.event_compare`, `lint`, and `hoi4.event_render` to review the result; comparison refreshes the edited source by default.
+
+Static analysis cannot prove runtime conditions, random outcomes, delayed scheduling, or arbitrary meta-generated text. Those limits are reported in diagnostics and artifacts rather than hidden or guessed. The server never launches or captures Hearts of Iron IV.

package/docs/focus.md

@@ -1,6 +1,6 @@
 # Focus trees
 
-Use `hoi4.focus_inspect`, `hoi4.focus_render`, and `hoi4.focus_rewrite` for national focus trees and continuous focus palettes. Start with `hoi4.mods` when the mod ID is not known.
+Use `hoi4.focus_inspect`, `hoi4.focus_render`, and `hoi4.focus_rewrite` for national focus trees and continuous focus palettes. Omit `workspaceId` when the MCP working directory is inside the target mod.
 
 ## Create a tree
 

package/docs/gui.md

@@ -1,6 +1,6 @@
 # Scripted GUIs
 
-Use `hoi4.gui_inspect`, `hoi4.gui_render`, and `hoi4.gui_rewrite` for `.gui`, `.gfx`, `common/scripted_guis`, localisation, sprites, fonts, and linked decision entry points. Start with `hoi4.mods` when the mod ID is not known.
+Use `hoi4.gui_inspect`, `hoi4.gui_render`, and `hoi4.gui_rewrite` for `.gui`, `.gfx`, `common/scripted_guis`, localisation, sprites, fonts, and linked decision entry points. Omit `workspaceId` when the MCP working directory is inside the target mod.
 
 ## Create a GUI
 
@@ -34,4 +34,6 @@ Inspection checks missing assets and localisation, invalid sizes, overlap, clipp
 
 The renderer does not run the game engine. Each render includes a fidelity report that separates fields it models from fields it approximates, ignores, cannot resolve, or does not support. Treat that report as part of the review.
 
+Unresolved runtime localisation expressions such as `[GetValue]` and `[?variable|format]` render as the compact placeholder `[X]`; provide scenario values when the exact text 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.

package/docs/map.md

@@ -1,6 +1,6 @@
 # Maps
 
-Use `hoi4.map_inspect`, `hoi4.map_render`, and `hoi4.map_rewrite` for provinces, states, strategic regions, adjacency, supply nodes, railways, positions, ownership, cores, claims, resources, buildings, and localisation. Start with `hoi4.mods` when the mod ID is not known.
+Use `hoi4.map_inspect`, `hoi4.map_render`, and `hoi4.map_rewrite` for provinces, states, strategic regions, adjacency, supply nodes, railways, positions, ownership, cores, claims, resources, buildings, and localisation. Omit `workspaceId` when the MCP working directory is inside the target mod.
 
 ## Create or reshape map content
 

package/docs/setup.md

@@ -2,18 +2,21 @@
 
 HOI4 Agent Tools requires Node.js 22 or 24.
 
-## Install and initialize
+## Install
 
 ```bash
-npm install --global hoi4-agent-tools@1.1.0
-hoi4-agent-tools-setup --init
+npm install --global hoi4-agent-tools
 ```
 
-The setup command discovers standard HOI4 game and mod locations, creates a separate storage folder for generated workspace data, and writes the default per-user config. Each configured mod root is a parent folder whose immediate child directories are individual mods. Every discovered mod is writable through the three rewrite tools; no per-mod write switch or approval step is required. The installed game remains reference-only.
+Set the MCP process working directory to the mod being edited. The server creates its local workspace in memory, keeps generated artifacts in the per-user data directory, and starts without a config file. The installed game is detected when available for vanilla references; it is not required for source inspection or offline rendering.
 
-After connecting the MCP server, call `hoi4.mods` to confirm which mods are available.
+When the MCP server starts with its working directory inside a mod, every focus, GUI, map, and event call uses that mod automatically. Omit `workspaceId`. Explicit `workspaceId` values remain available for configured multi-mod or remote deployments.
 
-## Override discovered paths
+## Optional persistent configuration
+
+Use `--init` only when you need several mod roots, a fixed game path, or a shared/remote process:
+
+### Configure explicit paths
 
 Use explicit paths when discovery is incomplete or when you want to expose more than one mod root:
 
@@ -22,7 +25,7 @@ hoi4-agent-tools-setup --init --mod-root /projects/hoi4-mods --mod-root /worksho
 ```
 
 - `--mod-root PATH` adds a parent folder containing mods. Repeat it for additional locations.
-- `--game-root PATH` selects the installed game folder used as a read-only reference.
+- `--game-root PATH` selects the installed game folder used for vanilla references.
 - `--workspace-storage-root PATH` selects where indexes, renders, and other generated workspace files are stored.
 - `--config PATH` writes or reads a config at a custom path instead of the default per-user location.
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "hoi4-agent-tools",
   "mcpName": "io.github.klimPaskov/hoi4-agent-tools",
-  "version": "1.1.0",
-  "description": "MCP tools for coding agents to create and clean HOI4 focus trees, scripted GUIs, and maps",
+  "version": "2.0.0",
+  "description": "Analyze HOI4 event chains; create and clean focus trees, scripted GUIs, and maps with coding agents.",
   "type": "module",
   "license": "Apache-2.0",
   "author": "HOI4 Agent Tools contributors",
@@ -21,6 +21,8 @@
     "coding-agents",
     "clausewitz",
     "focus-trees",
+    "event-chains",
+    "hoi4-events",
     "scripted-gui",
     "hoi4-map"
   ],
@@ -31,6 +33,7 @@
     "dist/",
     "docs/README.md",
     "docs/setup.md",
+    "docs/events.md",
     "docs/focus.md",
     "docs/gui.md",
     "docs/map.md",
@@ -60,10 +63,11 @@
     "test:local": "tsx scripts/run-local-tests.ts",
     "test:coverage": "vitest run --coverage",
     "benchmark": "node --expose-gc --import tsx scripts/benchmark.ts",
-    "fixtures:generate": "npm run fixtures:generate:focus && npm run fixtures:generate:gui && npm run fixtures:generate:map",
+    "fixtures:generate": "npm run fixtures:generate:focus && npm run fixtures:generate:gui && npm run fixtures:generate:map && npm run fixtures:generate:event",
     "fixtures:generate:focus": "tsx scripts/generate-fixtures.ts",
     "fixtures:generate:gui": "tsx scripts/generate-gui-fixture.ts",
     "fixtures:generate:map": "tsx scripts/generate-map-fixture.ts",
+    "fixtures:generate:event": "tsx scripts/generate-event-fixture.ts",
     "fixtures:check": "npm run fixtures:generate && tsx scripts/check-generated.ts fixtures",
     "schemas:generate": "tsx scripts/generate-schemas.ts",
     "schemas:check": "tsx scripts/generate-schemas.ts && tsx scripts/check-generated.ts schemas",

package/server.json

@@ -2,8 +2,8 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.klimPaskov/hoi4-agent-tools",
   "title": "HOI4 Agent Tools",
-  "description": "Create and clean HOI4 focus trees, scripted GUIs, and maps with coding agents.",
-  "version": "1.1.0",
+  "description": "Analyze HOI4 event chains; create and clean focus trees, scripted GUIs, and maps with coding agents.",
+  "version": "2.0.0",
   "repository": {
     "url": "https://github.com/klimPaskov/hoi4-agent-tools",
     "source": "github"
@@ -13,7 +13,7 @@
     {
       "registryType": "npm",
       "identifier": "hoi4-agent-tools",
-      "version": "1.1.0",
+      "version": "2.0.0",
       "transport": {
         "type": "stdio"
       }

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

@@ -1,54 +0,0 @@
-import { z } from 'zod/v4';
-import { compareCodeUnits } from '../../core/canonical.js';
-import { emptyServiceResult } from '../../core/result.js';
-import { nonNegativeIntegerSchema } from '../server/output-schemas.js';
-import { errorResult, strictOperationResultSchema, toolResult } from '../server/result.js';
-const modsOutputSchema = strictOperationResultSchema(z
-    .object({
-    count: nonNegativeIntegerSchema,
-    mods: z
-        .array(z
-        .object({
-        id: z.string().min(1).max(64),
-        name: z.string().min(1).max(256),
-        writable: z.boolean(),
-    })
-        .strict())
-        .max(1_000),
-})
-    .strict());
-export function registerModsTool(server, engine, context) {
-    server.registerTool('hoi4.mods', {
-        title: 'List available HOI4 mods',
-        description: 'List configured HOI4 mod workspaces, optionally selecting one by ID.',
-        inputSchema: z.object({ workspaceId: z.string().min(1).max(64).optional() }).strict(),
-        outputSchema: modsOutputSchema,
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-    }, ({ workspaceId }) => {
-        try {
-            const mods = (workspaceId === undefined
-                ? engine.list(context.principal)
-                : [engine.status(workspaceId, context.principal)])
-                .filter(({ kind }) => kind === 'mod')
-                .sort((left, right) => compareCodeUnits(left.id, right.id));
-            const result = emptyServiceResult(workspaceId ?? '', {
-                count: mods.length,
-                mods: mods.map(({ id, name, writable }) => ({
-                    id,
-                    name,
-                    writable,
-                })),
-            });
-            result.code = 'MODS_LISTED';
-            return toolResult(result);
-        }
-        catch (error) {
-            return errorResult(error, workspaceId ?? '');
-        }
-    });
-}