hoi4-agent-tools 1.1.0 → 1.2.0

package/dist/hoi4_agent_tools/focus/native-effects.js

@@ -5,7 +5,7 @@
  * Source: the official HOI4 1.19.2 effects documentation reviewed 2026-07-10.
  * Keep this list synchronized during compatibility reviews.
  */
-export const nativeFocusEffectKeys = new Set([
+export const nativeEffectKeys = new Set([
     'activate_advisor',
     'activate_decision',
     'activate_mission',
@@ -560,3 +560,5 @@ export const nativeFocusEffectKeys = new Set([
     'while_loop_effect',
     'white_peace',
 ]);
+/** Backward-compatible focus-domain name for the shared official effect catalog. */
+export const nativeFocusEffectKeys = nativeEffectKeys;

package/dist/hoi4_agent_tools/mcp/resources/register.js

@@ -6,7 +6,7 @@ const artifactChunkMetadataKey = 'io.github.klimpaskov/hoi4-agent-tools.artifact
 const fatalUtf8Decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
 const artifactResourceMetadata = {
     title: 'HOI4 review artifact',
-    description: 'Complete plans, diagnostics, layouts, previews, and diffs. Reads accept zero-based byte offset and positive byte length query selectors; each response reports its exact byte range and continuation URI in _meta.',
+    description: 'Complete plans, diagnostics, layouts, previews, event graphs, routes, state and scope reports, comparisons, and diffs. Reads accept zero-based byte offset and positive byte length query selectors; each response reports its exact byte range and continuation URI in _meta.',
     _meta: {
         [artifactChunkMetadataKey]: {
             version: 1,

package/dist/hoi4_agent_tools/mcp/server/create.js

@@ -4,7 +4,9 @@ import { registerModsTool } from '../tools/mods.js';
 import { registerFocusTools } from '../tools/focus.js';
 import { registerGuiTools } from '../tools/gui.js';
 import { registerMapTools } from '../tools/map.js';
+import { registerEventTools } from '../tools/event.js';
 import { registerMcpResources } from '../resources/register.js';
+export const SERVER_INSTRUCTIONS = 'Use hoi4.mods to select a workspace. Use hoi4.event_inspect for scan, roots, trace, explain_path, state_flow, lint, and impact; hoi4.event_render and hoi4.event_compare return linked evidence. JSON resources are authoritative. Event tools are read-only. Only focus, GUI, and map rewrite tools edit configured mods.';
 export function createMcpServer(engine, context = {}) {
     const server = new McpServer({
         name: PACKAGE_NAME,
@@ -12,11 +14,13 @@ export function createMcpServer(engine, context = {}) {
         websiteUrl: 'https://github.com/klimPaskov/hoi4-agent-tools',
     }, {
         capabilities: { logging: {} },
+        instructions: SERVER_INSTRUCTIONS,
     });
     registerModsTool(server, engine, context);
     registerFocusTools(server, engine, context);
     registerGuiTools(server, engine, context);
     registerMapTools(server, engine, context);
+    registerEventTools(server, engine, context);
     registerMcpResources(server, engine, context);
     return server;
 }

package/dist/hoi4_agent_tools/mcp/server/result.js

@@ -42,24 +42,18 @@ const emptyToolDataSchema = z.object({}).strict();
 const compactPublicOperationResultSchema = z
     .object({
     status: z.enum(['ok', 'blocked', 'error']),
-    code: z.string().max(256),
-    workspaceId: z.string().max(64),
-    filesScanned: z.array(z.string().max(4096)).max(MAX_INLINE_FILES_SCANNED),
-    proposedFiles: z.array(z.string().max(1024)).max(MAX_INLINE_PROPOSED_FILES),
-    changedFiles: z.array(z.string().max(1024)).max(MAX_INLINE_CHANGED_FILES),
+    code: z.string(),
+    workspaceId: z.string(),
+    filesScanned: z.array(z.unknown()).max(MAX_INLINE_FILES_SCANNED),
+    proposedFiles: z.array(z.unknown()).max(MAX_INLINE_PROPOSED_FILES),
+    changedFiles: z.array(z.unknown()).max(MAX_INLINE_CHANGED_FILES),
     diagnostics: z.array(z.unknown()).max(MAX_INLINE_DIAGNOSTICS),
     artifacts: z.array(z.unknown()).max(MAX_INLINE_ARTIFACT_LINKS),
-    validation: z
-        .object({
-        passed: z.boolean(),
-        checks: z.array(z.unknown()).max(MAX_INLINE_VALIDATION_CHECKS),
-    })
-        .strict(),
+    validation: z.unknown(),
     blockers: z.array(z.unknown()).max(MAX_INLINE_BLOCKERS),
-    data: z.record(z.string().max(256), z.unknown()),
+    data: z.object({}).catchall(z.unknown()),
 })
-    .strict()
-    .describe('Stable operation envelope; data is tool-specific and artifacts link bulk evidence.');
+    .strict();
 /**
  * Advertise one compact operation envelope while retaining exact per-tool runtime validation.
  * The generic operation-result schema remains available for stored envelopes.

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

@@ -0,0 +1,459 @@
+import { z } from 'zod/v4';
+import { publicArtifactLink } from '../../core/artifacts.js';
+import { compareCodeUnits } from '../../core/canonical.js';
+import { emptyServiceResult } from '../../core/result.js';
+import { EventChainViewer, eventDiagnostics, } from '../../event/service.js';
+import { eventDirectionSchema, eventGraphReferenceSchema, eventImpactSubjectSchema, eventInspectModeSchema, eventProposedSourceSchema, eventRenderViewSchema, eventSelectorSchema, eventStateSubjectSchema, } from '../../schemas/event.js';
+import { workspaceIdSchema } from '../../schemas/common.js';
+import { compactValidatedInputSchema } from '../server/context-schemas.js';
+import { nonNegativeIntegerSchema, sha256Schema } from '../server/output-schemas.js';
+import { progressReporter } from '../server/progress.js';
+import { errorResult, setInlineFilesScanned, strictOperationResultSchema, toolResult, } from '../server/result.js';
+const nestedSelectorSchema = compactValidatedInputSchema(eventSelectorSchema, 'Event selector; see docs/events.md.');
+const nestedStateSubjectSchema = compactValidatedInputSchema(eventStateSubjectSchema, 'State kind and name.');
+const nestedImpactSubjectSchema = compactValidatedInputSchema(eventImpactSubjectSchema, 'Impact kind and name.');
+const nestedGraphReferenceSchema = compactValidatedInputSchema(eventGraphReferenceSchema, 'Cached revision or graph artifact URI.');
+const nestedProposedSourceSchema = compactValidatedInputSchema(eventProposedSourceSchema, 'In-memory source overlay; never written.');
+const eventInspectInputSchema = z
+    .object({
+    workspaceId: workspaceIdSchema,
+    mode: eventInspectModeSchema,
+    selector: nestedSelectorSchema.optional(),
+    from: nestedSelectorSchema.optional(),
+    to: nestedSelectorSchema.optional(),
+    direction: eventDirectionSchema.optional(),
+    maxDepth: z.number().int().min(1).max(64).optional(),
+    maxNodes: z.number().int().min(1).max(5_000).optional(),
+    maxEdges: z.number().int().min(1).max(20_000).optional(),
+    expandHelpers: z.boolean().optional(),
+    stateSubject: nestedStateSubjectSchema.optional(),
+    impactSubject: nestedImpactSubjectSchema.optional(),
+    refresh: z.boolean().optional(),
+})
+    .strict()
+    .superRefine((value, context) => {
+    if (value.mode === 'trace' && value.selector === undefined) {
+        context.addIssue({ code: 'custom', path: ['selector'], message: 'Trace requires selector' });
+    }
+    if (value.mode === 'explain_path' && (value.from === undefined || value.to === undefined)) {
+        context.addIssue({
+            code: 'custom',
+            path: value.from === undefined ? ['from'] : ['to'],
+            message: 'Path explanation requires from and to',
+        });
+    }
+    if (value.mode === 'impact' && value.impactSubject === undefined) {
+        context.addIssue({
+            code: 'custom',
+            path: ['impactSubject'],
+            message: 'Impact analysis requires impactSubject',
+        });
+    }
+});
+const eventRenderInputSchema = z
+    .object({
+    workspaceId: workspaceIdSchema,
+    view: eventRenderViewSchema,
+    selector: nestedSelectorSchema.optional(),
+    direction: eventDirectionSchema.optional(),
+    maxDepth: z.number().int().min(1).max(64).optional(),
+    maxNodes: z.number().int().min(1).max(240).optional(),
+    expandHelpers: z.boolean().optional(),
+    includeHtml: z.boolean().optional(),
+    refresh: z.boolean().optional(),
+})
+    .strict();
+const eventCompareInputSchema = z
+    .object({
+    workspaceId: workspaceIdSchema,
+    before: nestedGraphReferenceSchema.optional(),
+    after: nestedGraphReferenceSchema.optional(),
+    proposedSources: z.array(nestedProposedSourceSchema).min(1).max(64).optional(),
+    render: z.boolean().optional(),
+    maxRenderNodes: z.number().int().min(1).max(240).optional(),
+    refresh: z.boolean().optional(),
+})
+    .strict()
+    .superRefine((value, context) => {
+    if (value.after !== undefined && value.proposedSources !== undefined) {
+        context.addIssue({
+            code: 'custom',
+            path: ['after'],
+            message: 'after and proposedSources are mutually exclusive',
+        });
+    }
+});
+const eventGraphCountsSchema = z
+    .object({
+    events: nonNegativeIntegerSchema,
+    options: nonNegativeIntegerSchema,
+    entries: nonNegativeIntegerSchema,
+    helpers: nonNegativeIntegerSchema,
+    unresolvedNodes: nonNegativeIntegerSchema,
+    terminals: nonNegativeIntegerSchema,
+    edges: nonNegativeIntegerSchema,
+    derivedEdges: nonNegativeIntegerSchema,
+    stateAccesses: nonNegativeIntegerSchema,
+    issues: nonNegativeIntegerSchema,
+    diagnostics: nonNegativeIntegerSchema,
+    blockingDiagnostics: nonNegativeIntegerSchema,
+    skippedSources: nonNegativeIntegerSchema,
+    artifacts: nonNegativeIntegerSchema,
+})
+    .strict();
+const inspectBoundarySchema = z
+    .object({
+    direction: eventDirectionSchema,
+    maxDepth: nonNegativeIntegerSchema,
+    maxNodes: nonNegativeIntegerSchema,
+    maxEdges: nonNegativeIntegerSchema,
+    expandHelpers: z.boolean(),
+    refresh: z.boolean(),
+})
+    .strict();
+const renderHashSchema = z
+    .object({
+    json: sha256Schema,
+    svg: sha256Schema,
+    png: sha256Schema,
+    html: sha256Schema.optional(),
+})
+    .strict();
+const eventInspectOutputSchema = strictOperationResultSchema(z
+    .object({
+    mode: eventInspectModeSchema,
+    revision: sha256Schema,
+    graphHash: sha256Schema,
+    counts: eventGraphCountsSchema,
+    boundary: inspectBoundarySchema,
+})
+    .strict());
+const eventRenderOutputSchema = strictOperationResultSchema(z
+    .object({
+    view: eventRenderViewSchema,
+    revision: sha256Schema,
+    graphHash: sha256Schema,
+    layoutHash: sha256Schema,
+    hashes: renderHashSchema,
+    counts: eventGraphCountsSchema.extend({
+        selectedNodes: nonNegativeIntegerSchema,
+        omittedNodes: nonNegativeIntegerSchema,
+        branchRenders: nonNegativeIntegerSchema,
+    }),
+    boundary: z
+        .object({
+        direction: eventDirectionSchema,
+        maxDepth: nonNegativeIntegerSchema,
+        maxNodes: nonNegativeIntegerSchema,
+        expandHelpers: z.boolean(),
+        includeHtml: z.boolean(),
+        refresh: z.boolean(),
+    })
+        .strict(),
+})
+    .strict());
+const eventCompareOutputSchema = strictOperationResultSchema(z
+    .object({
+    beforeRevision: sha256Schema,
+    afterRevision: sha256Schema,
+    beforeGraphHash: sha256Schema,
+    afterGraphHash: sha256Schema,
+    renderHashes: renderHashSchema.optional(),
+    counts: z
+        .object({
+        changes: nonNegativeIntegerSchema,
+        addedNodes: nonNegativeIntegerSchema,
+        removedNodes: nonNegativeIntegerSchema,
+        changedNodes: nonNegativeIntegerSchema,
+        addedEdges: nonNegativeIntegerSchema,
+        removedEdges: nonNegativeIntegerSchema,
+        changedEdges: nonNegativeIntegerSchema,
+        addedStateAccesses: nonNegativeIntegerSchema,
+        removedStateAccesses: nonNegativeIntegerSchema,
+        changedStateAccesses: nonNegativeIntegerSchema,
+        addedStateLinks: nonNegativeIntegerSchema,
+        removedStateLinks: nonNegativeIntegerSchema,
+        changedStateLinks: nonNegativeIntegerSchema,
+        addedDiagnostics: nonNegativeIntegerSchema,
+        resolvedDiagnostics: nonNegativeIntegerSchema,
+        addedUnresolved: nonNegativeIntegerSchema,
+        resolvedUnresolved: nonNegativeIntegerSchema,
+        disconnectedRoots: nonNegativeIntegerSchema,
+        disconnectedBranches: nonNegativeIntegerSchema,
+        disconnectedTerminals: nonNegativeIntegerSchema,
+        beforeSkippedSources: nonNegativeIntegerSchema,
+        afterSkippedSources: nonNegativeIntegerSchema,
+        artifacts: nonNegativeIntegerSchema,
+    })
+        .strict(),
+    boundary: z
+        .object({
+        proposedSources: nonNegativeIntegerSchema,
+        render: z.boolean(),
+        maxRenderNodes: nonNegativeIntegerSchema,
+        refresh: z.boolean(),
+    })
+        .strict(),
+})
+    .strict());
+const readOnlyEventTool = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+};
+function graphCounts(graph, artifacts) {
+    const diagnostics = eventDiagnostics(graph);
+    return {
+        events: graph.statistics.eventCount,
+        options: graph.statistics.optionCount,
+        entries: graph.statistics.entryCount,
+        helpers: graph.statistics.helperCount,
+        unresolvedNodes: graph.statistics.unresolvedNodeCount,
+        terminals: graph.statistics.terminalCount,
+        edges: graph.statistics.edgeCount,
+        derivedEdges: graph.statistics.derivedEdgeCount,
+        stateAccesses: graph.statistics.stateAccessCount,
+        issues: graph.statistics.issueCount,
+        diagnostics: diagnostics.length,
+        blockingDiagnostics: diagnostics.filter(({ severity }) => severity === 'error' || severity === 'blocker').length,
+        skippedSources: graph.skippedSourceCount,
+        artifacts,
+    };
+}
+function graphValidation(graph) {
+    const counts = graphCounts(graph, 0);
+    return {
+        passed: graph.complete && counts.blockingDiagnostics === 0,
+        checks: [
+            {
+                id: 'event-analysis',
+                passed: graph.complete && counts.blockingDiagnostics === 0,
+                message: graph.complete
+                    ? `${counts.blockingDiagnostics} blocking event-chain diagnostics; full evidence is linked`
+                    : `${graph.skippedSourceCount} event-analysis source(s) were skipped; full evidence is linked`,
+            },
+        ],
+    };
+}
+function inspectRequest(input, context, signal) {
+    return {
+        workspaceId: input.workspaceId,
+        mode: input.mode,
+        ...(input.selector === undefined
+            ? {}
+            : { selector: input.selector }),
+        ...(input.from === undefined
+            ? {}
+            : { from: input.from }),
+        ...(input.to === undefined ? {} : { to: input.to }),
+        ...(input.direction === undefined ? {} : { direction: input.direction }),
+        ...(input.maxDepth === undefined ? {} : { maxDepth: input.maxDepth }),
+        ...(input.maxNodes === undefined ? {} : { maxNodes: input.maxNodes }),
+        ...(input.maxEdges === undefined ? {} : { maxEdges: input.maxEdges }),
+        ...(input.expandHelpers === undefined ? {} : { expandHelpers: input.expandHelpers }),
+        ...(input.stateSubject === undefined ? {} : { stateSubject: input.stateSubject }),
+        ...(input.impactSubject === undefined ? {} : { impactSubject: input.impactSubject }),
+        ...(input.refresh === undefined ? {} : { refresh: input.refresh }),
+        ...(context.principal === undefined ? {} : { principal: context.principal }),
+        signal,
+    };
+}
+function renderRequest(input, context, signal) {
+    return {
+        workspaceId: input.workspaceId,
+        view: input.view,
+        ...(input.selector === undefined
+            ? {}
+            : { selector: input.selector }),
+        ...(input.direction === undefined ? {} : { direction: input.direction }),
+        ...(input.maxDepth === undefined ? {} : { maxDepth: input.maxDepth }),
+        ...(input.maxNodes === undefined ? {} : { maxNodes: input.maxNodes }),
+        ...(input.expandHelpers === undefined ? {} : { expandHelpers: input.expandHelpers }),
+        ...(input.includeHtml === undefined ? {} : { includeHtml: input.includeHtml }),
+        ...(input.refresh === undefined ? {} : { refresh: input.refresh }),
+        ...(context.principal === undefined ? {} : { principal: context.principal }),
+        signal,
+    };
+}
+function compareRequest(input, context, signal) {
+    return {
+        workspaceId: input.workspaceId,
+        ...(input.before === undefined
+            ? {}
+            : { before: input.before }),
+        ...(input.after === undefined
+            ? {}
+            : { after: input.after }),
+        ...(input.proposedSources === undefined
+            ? {}
+            : {
+                proposedSources: input.proposedSources,
+            }),
+        ...(input.render === undefined ? {} : { render: input.render }),
+        ...(input.maxRenderNodes === undefined ? {} : { maxRenderNodes: input.maxRenderNodes }),
+        ...(input.refresh === undefined ? {} : { refresh: input.refresh }),
+        ...(context.principal === undefined ? {} : { principal: context.principal }),
+        signal,
+    };
+}
+export function registerEventTools(server, engine, context) {
+    const viewer = new EventChainViewer(engine);
+    server.registerTool('hoi4.event_inspect', {
+        title: 'Inspect event chains',
+        description: 'Scan, find roots, trace, explain paths, inspect state flow, lint, or assess impact. Full source-linked reports are resources.',
+        inputSchema: eventInspectInputSchema,
+        outputSchema: eventInspectOutputSchema,
+        annotations: readOnlyEventTool,
+    }, async (input, extra) => {
+        const { workspaceId } = input;
+        try {
+            const progress = progressReporter(extra);
+            await progress.report(0, 3, 'Analyzing event chain');
+            const inspected = await viewer.inspect(inspectRequest(input, context, progress.signal));
+            await progress.report(2, 3, 'Linking complete event analysis');
+            const result = emptyServiceResult(workspaceId, {
+                mode: inspected.mode,
+                revision: inspected.graph.revision,
+                graphHash: inspected.graphHash,
+                counts: graphCounts(inspected.graph, inspected.artifacts.length),
+                boundary: {
+                    direction: input.direction ?? 'both',
+                    maxDepth: input.maxDepth ?? 8,
+                    maxNodes: input.maxNodes ?? 500,
+                    maxEdges: input.maxEdges ?? 2_000,
+                    expandHelpers: input.expandHelpers ?? (input.mode === 'explain_path' ? true : false),
+                    refresh: input.refresh ?? input.mode === 'scan',
+                },
+            });
+            result.code = inspected.graph.complete ? 'EVENT_INSPECTED' : 'EVENT_INSPECTED_PARTIAL';
+            setInlineFilesScanned(result, inspected.graph.filesScanned);
+            result.artifacts = inspected.artifacts.map(publicArtifactLink);
+            result.validation = graphValidation(inspected.graph);
+            await progress.report(3, 3, 'Event inspection complete');
+            return toolResult(result);
+        }
+        catch (error) {
+            return errorResult(error, workspaceId);
+        }
+    });
+    server.registerTool('hoi4.event_render', {
+        title: 'Render event chains',
+        description: 'Render deterministic JSON, SVG, PNG, and optional HTML for an event-chain view. Complete artifacts retain source links.',
+        inputSchema: eventRenderInputSchema,
+        outputSchema: eventRenderOutputSchema,
+        annotations: readOnlyEventTool,
+    }, async (input, extra) => {
+        const { workspaceId } = input;
+        try {
+            const progress = progressReporter(extra);
+            await progress.report(0, 3, 'Rendering event-chain view');
+            const rendered = await viewer.renderAndStore(renderRequest(input, context, progress.signal));
+            await progress.report(2, 3, 'Linking complete event renders');
+            const result = emptyServiceResult(workspaceId, {
+                view: rendered.render.view,
+                revision: rendered.graph.revision,
+                graphHash: rendered.graphHash,
+                layoutHash: rendered.render.layout.layoutHash,
+                hashes: rendered.render.hashes,
+                counts: {
+                    ...graphCounts(rendered.graph, rendered.artifacts.length),
+                    selectedNodes: rendered.render.selectedNodeIds.length,
+                    omittedNodes: rendered.render.omittedNodeCount,
+                    branchRenders: rendered.branches.length,
+                },
+                boundary: {
+                    direction: input.direction ?? 'both',
+                    maxDepth: input.maxDepth ?? 4,
+                    maxNodes: input.maxNodes ?? 120,
+                    expandHelpers: input.expandHelpers ?? false,
+                    includeHtml: input.includeHtml ?? false,
+                    refresh: input.refresh ?? false,
+                },
+            });
+            result.code = rendered.graph.complete ? 'EVENT_RENDERED' : 'EVENT_RENDERED_PARTIAL';
+            setInlineFilesScanned(result, rendered.graph.filesScanned);
+            result.artifacts = rendered.artifacts.map(publicArtifactLink);
+            result.validation = graphValidation(rendered.graph);
+            await progress.report(3, 3, 'Event render complete');
+            return toolResult(result);
+        }
+        catch (error) {
+            return errorResult(error, workspaceId);
+        }
+    });
+    server.registerTool('hoi4.event_compare', {
+        title: 'Compare event chains',
+        description: 'Compare cached, artifact-backed, current, or in-memory proposed event graphs without writing source. Full changes are resources.',
+        inputSchema: eventCompareInputSchema,
+        outputSchema: eventCompareOutputSchema,
+        annotations: readOnlyEventTool,
+    }, async (input, extra) => {
+        const { workspaceId } = input;
+        try {
+            const progress = progressReporter(extra);
+            await progress.report(0, 3, 'Comparing event-chain graphs');
+            const compared = await viewer.compareAndStore(compareRequest(input, context, progress.signal));
+            await progress.report(2, 3, 'Linking complete event comparison');
+            const { comparison } = compared;
+            const result = emptyServiceResult(workspaceId, {
+                beforeRevision: comparison.beforeRevision,
+                afterRevision: comparison.afterRevision,
+                beforeGraphHash: comparison.beforeGraphHash,
+                afterGraphHash: comparison.afterGraphHash,
+                ...(compared.render === undefined ? {} : { renderHashes: compared.render.hashes }),
+                counts: {
+                    changes: comparison.changes.length,
+                    addedNodes: comparison.addedNodeIds.length,
+                    removedNodes: comparison.removedNodeIds.length,
+                    changedNodes: comparison.changedNodeIds.length,
+                    addedEdges: comparison.addedEdgeIds.length,
+                    removedEdges: comparison.removedEdgeIds.length,
+                    changedEdges: comparison.changedEdgeIds.length,
+                    addedStateAccesses: comparison.addedStateAccessIds.length,
+                    removedStateAccesses: comparison.removedStateAccessIds.length,
+                    changedStateAccesses: comparison.changedStateAccessIds.length,
+                    addedStateLinks: comparison.addedStateLinkIds.length,
+                    removedStateLinks: comparison.removedStateLinkIds.length,
+                    changedStateLinks: comparison.changedStateLinkIds.length,
+                    addedDiagnostics: comparison.addedIssueIds.length,
+                    resolvedDiagnostics: comparison.resolvedIssueIds.length,
+                    addedUnresolved: comparison.addedUnresolvedIds.length,
+                    resolvedUnresolved: comparison.resolvedUnresolvedIds.length,
+                    disconnectedRoots: comparison.newlyDisconnectedRootIds.length,
+                    disconnectedBranches: comparison.newlyDisconnectedBranchIds.length,
+                    disconnectedTerminals: comparison.newlyDisconnectedTerminalIds.length,
+                    beforeSkippedSources: compared.before.skippedSourceCount,
+                    afterSkippedSources: compared.after.skippedSourceCount,
+                    artifacts: compared.artifacts.length,
+                },
+                boundary: {
+                    proposedSources: input.proposedSources?.length ?? 0,
+                    render: input.render ?? true,
+                    maxRenderNodes: input.maxRenderNodes ?? 120,
+                    refresh: compared.refresh,
+                },
+            });
+            result.code =
+                compared.before.complete && compared.after.complete
+                    ? 'EVENT_COMPARED'
+                    : 'EVENT_COMPARED_PARTIAL';
+            setInlineFilesScanned(result, [...new Set([...compared.before.filesScanned, ...compared.after.filesScanned])].sort(compareCodeUnits));
+            result.artifacts = compared.artifacts.map(publicArtifactLink);
+            const beforeValidation = graphValidation(compared.before);
+            const afterValidation = graphValidation(compared.after);
+            result.validation = {
+                passed: beforeValidation.passed && afterValidation.passed,
+                checks: [...beforeValidation.checks, ...afterValidation.checks].map((check, index) => ({
+                    ...check,
+                    id: `${index === 0 ? 'before' : 'after'}-${check.id}`,
+                })),
+            };
+            await progress.report(3, 3, 'Event comparison complete');
+            return toolResult(result);
+        }
+        catch (error) {
+            return errorResult(error, workspaceId);
+        }
+    });
+}

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 = '1.2.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.