hoi4-agent-tools 1.1.0 → 2.0.0

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 = engine.resolver.resolveWorkspaceId(input.workspaceId, context.principal);
+        try {
+            const progress = progressReporter(extra);
+            await progress.report(0, 3, 'Analyzing event chain');
+            const inspected = await viewer.inspect(inspectRequest({ ...input, workspaceId }, 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 = engine.resolver.resolveWorkspaceId(input.workspaceId, context.principal);
+        try {
+            const progress = progressReporter(extra);
+            await progress.report(0, 3, 'Rendering event-chain view');
+            const rendered = await viewer.renderAndStore(renderRequest({ ...input, workspaceId }, 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 = engine.resolver.resolveWorkspaceId(input.workspaceId, context.principal);
+        try {
+            const progress = progressReporter(extra);
+            await progress.report(0, 3, 'Comparing event-chain graphs');
+            const compared = await viewer.compareAndStore(compareRequest({ ...input, workspaceId }, 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/mcp/tools/focus.js

@@ -451,7 +451,8 @@ export function registerFocusTools(server, engine, context) {
         outputSchema: focusInspectOutputSchema,
         annotations: artifactProducing,
     }, async (input, extra) => {
-        const { workspaceId, relativePath } = input;
+        const { workspaceId: requestedWorkspaceId, relativePath } = input;
+        const workspaceId = engine.resolver.resolveWorkspaceId(requestedWorkspaceId, context.principal);
         try {
             const progress = progressReporter(extra);
             await progress.report(0, 3, 'Building shared workspace index');
@@ -667,7 +668,8 @@ export function registerFocusTools(server, engine, context) {
         outputSchema: focusRenderOutputSchema,
         annotations: artifactProducing,
     }, async (input, extra) => {
-        const { workspaceId, relativePath } = input;
+        const { workspaceId: requestedWorkspaceId, relativePath } = input;
+        const workspaceId = engine.resolver.resolveWorkspaceId(requestedWorkspaceId, context.principal);
         try {
             const progress = progressReporter(extra);
             await progress.report(0, 3, 'Importing and indexing focus source');
@@ -790,7 +792,8 @@ export function registerFocusTools(server, engine, context) {
             openWorldHint: false,
         },
     }, async (input, extra) => {
-        const { workspaceId, relativePath, createIfMissing, horizontalSpacing, verticalSpacing, padding, reviewScale, } = input;
+        const { workspaceId: requestedWorkspaceId, relativePath, createIfMissing, horizontalSpacing, verticalSpacing, padding, reviewScale, } = input;
+        const workspaceId = engine.resolver.resolveWorkspaceId(requestedWorkspaceId, context.principal);
         try {
             requireServerScope(context, 'hoi4:write');
             const progress = progressReporter(extra);

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

@@ -149,7 +149,8 @@ export function registerGuiTools(server, engine, context) {
         inputSchema: guiInspectInput,
         outputSchema: guiScanOutputSchema,
         annotations: artifactProducing,
-    }, async ({ workspaceId, windowName, scenario, relatedScenarios }, extra) => {
+    }, async ({ workspaceId: requestedWorkspaceId, windowName, scenario, relatedScenarios }, extra) => {
+        const workspaceId = engine.resolver.resolveWorkspaceId(requestedWorkspaceId, context.principal);
         try {
             const progress = progressReporter(extra);
             await progress.report(0, 3, 'Building shared index and GUI inspection');
@@ -253,7 +254,8 @@ export function registerGuiTools(server, engine, context) {
         }
     });
     const render = async (input, extra, code) => {
-        const { workspaceId, windowName } = input;
+        const workspaceId = engine.resolver.resolveWorkspaceId(input.workspaceId, context.principal);
+        const { windowName } = input;
         try {
             const progress = progressReporter(extra);
             await progress.report(0, 4, 'Building shared index and GUI source graph');
@@ -444,7 +446,8 @@ export function registerGuiTools(server, engine, context) {
             openWorldHint: false,
         },
     }, async (input, extra) => {
-        const { workspaceId, relativePath, windowName, scenario } = input;
+        const workspaceId = engine.resolver.resolveWorkspaceId(input.workspaceId, context.principal);
+        const { relativePath, windowName, scenario } = input;
         try {
             requireServerScope(context, 'hoi4:write');
             const progress = progressReporter(extra);

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

@@ -364,7 +364,8 @@ export function registerMapTools(server, engine, context) {
             .strict(),
         outputSchema: mapWorkspaceInspectOutputSchema,
         annotations: artifactProducing,
-    }, async ({ workspaceId, provinceIds, stateIds, regionIds, allocationRequests }, extra) => {
+    }, async ({ workspaceId: requestedWorkspaceId, provinceIds, stateIds, regionIds, allocationRequests }, extra) => {
+        const workspaceId = engine.resolver.resolveWorkspaceId(requestedWorkspaceId, context.principal);
         try {
             const progress = progressReporter(extra);
             await progress.report(0, 3, 'Inspecting and validating the map');
@@ -512,7 +513,8 @@ export function registerMapTools(server, engine, context) {
             .strict(),
         outputSchema: mapRenderOutputSchema,
         annotations: artifactProducing,
-    }, async ({ workspaceId, layer, overlays, scale }, extra) => {
+    }, async ({ workspaceId: requestedWorkspaceId, layer, overlays, scale }, extra) => {
+        const workspaceId = engine.resolver.resolveWorkspaceId(requestedWorkspaceId, context.principal);
         try {
             const progress = progressReporter(extra);
             await progress.report(0, 3, 'Rendering offline map layer');
@@ -557,7 +559,8 @@ export function registerMapTools(server, engine, context) {
             idempotentHint: false,
             openWorldHint: false,
         },
-    }, async ({ workspaceId, operations, diffScale }, extra) => {
+    }, async ({ workspaceId: requestedWorkspaceId, operations, diffScale }, extra) => {
+        const workspaceId = engine.resolver.resolveWorkspaceId(requestedWorkspaceId, context.principal);
         try {
             requireServerScope(context, 'hoi4:write');
             const progress = progressReporter(extra);

package/dist/hoi4_agent_tools/runtime.js

@@ -1,9 +1,11 @@
+import { stat } from 'node:fs/promises';
 import path from 'node:path';
 import { homedir } from 'node:os';
-import { loadConfiguration } from './core/configuration.js';
+import { loadConfiguration, serverConfigurationSchema, } from './core/configuration.js';
 import { CoreEngine } from './core/engine.js';
 import { ServiceError } from './core/result.js';
 import { WorkspaceResolver } from './core/workspace.js';
+import { CONFIG_VERSION } from './version.js';
 export function defaultConfigurationPath() {
     const configRoot = process.env.APPDATA ?? process.env.XDG_CONFIG_HOME ?? path.join(homedir(), '.config');
     return path.join(configRoot, 'hoi4-agent-tools', 'config.json');
@@ -21,8 +23,116 @@ export function configurationPath(arguments_ = process.argv.slice(2)) {
         return path.resolve(process.env.HOI4_AGENT_CONFIG);
     return defaultConfigurationPath();
 }
+async function isDirectory(candidate) {
+    try {
+        return (await stat(candidate)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function isFile(candidate) {
+    try {
+        return (await stat(candidate)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function findCurrentModRoot(start = process.cwd()) {
+    for (let cursor = path.resolve(start);;) {
+        if ((await isFile(path.join(cursor, 'descriptor.mod'))) ||
+            ((await isDirectory(path.join(cursor, 'common'))) &&
+                ((await isDirectory(path.join(cursor, 'history'))) ||
+                    (await isDirectory(path.join(cursor, 'interface'))) ||
+                    (await isDirectory(path.join(cursor, 'map')))))) {
+            return cursor;
+        }
+        const parent = path.dirname(cursor);
+        if (parent === cursor)
+            break;
+        cursor = parent;
+    }
+    throw new ServiceError('AUTO_MOD_ROOT_NOT_FOUND', 'Start the MCP from inside a Hearts of Iron IV mod or configure a server workspace', { currentDirectory: path.resolve(start) });
+}
+async function firstExistingDirectory(candidates) {
+    for (const candidate of candidates) {
+        if (await isDirectory(candidate))
+            return path.resolve(candidate);
+    }
+    return undefined;
+}
+function automaticGameRootCandidates() {
+    const home = homedir();
+    return [
+        ...(process.env.HOI4_GAME_ROOT === undefined ? [] : [process.env.HOI4_GAME_ROOT]),
+        path.join(process.env['ProgramFiles(x86)'] ?? 'C:\\Program Files (x86)', 'Steam', 'steamapps', 'common', 'Hearts of Iron IV'),
+        path.join(home, '.local', 'share', 'Steam', 'steamapps', 'common', 'Hearts of Iron IV'),
+        path.join(home, '.steam', 'steam', 'steamapps', 'common', 'Hearts of Iron IV'),
+        path.join(home, 'Library', 'Application Support', 'Steam', 'steamapps', 'common', 'Hearts of Iron IV'),
+    ];
+}
+function automaticStorageRoots() {
+    const home = homedir();
+    const dataRoot = process.env.XDG_DATA_HOME ?? process.env.LOCALAPPDATA ?? path.join(home, '.local', 'share');
+    const stateRoot = process.env.XDG_STATE_HOME ?? process.env.LOCALAPPDATA ?? path.join(home, '.local', 'state');
+    return {
+        serverStateRoot: path.join(stateRoot, 'hoi4-agent-tools', 'state'),
+        workspaceStorageRoot: path.join(dataRoot, 'hoi4-agent-tools', 'workspaces'),
+    };
+}
+function automaticWorkspaceId(modRoot) {
+    const slug = path
+        .basename(modRoot)
+        .normalize('NFKD')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/gu, '_')
+        .replace(/^_+|_+$/gu, '')
+        .slice(0, 48);
+    return `auto_${slug.length === 0 ? 'mod' : slug}`;
+}
+/** Build an in-memory configuration when a local agent starts inside a mod. */
+export async function automaticConfiguration(start = process.cwd()) {
+    const modRoot = await findCurrentModRoot(start);
+    const gameRoot = await firstExistingDirectory(automaticGameRootCandidates());
+    const storage = automaticStorageRoots();
+    return serverConfigurationSchema.parse({
+        version: CONFIG_VERSION,
+        serverStateRoot: storage.serverStateRoot,
+        workspaceStorageRoot: storage.workspaceStorageRoot,
+        ...(gameRoot === undefined ? {} : { gameRoot }),
+        workspaces: [
+            {
+                id: automaticWorkspaceId(modRoot),
+                name: path.basename(modRoot),
+                root: modRoot,
+            },
+        ],
+    });
+}
+async function configurationExists(configPath) {
+    try {
+        return (await stat(configPath)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
 export async function createEngine(configPath = configurationPath()) {
-    const configuration = await loadConfiguration(configPath);
+    let configuration;
+    try {
+        configuration = await loadConfiguration(configPath);
+    }
+    catch (error) {
+        const useAutomaticConfiguration = configPath === defaultConfigurationPath() &&
+            process.env.HOI4_AGENT_CONFIG === undefined &&
+            error instanceof ServiceError &&
+            error.code === 'CONFIG_READ_FAILED' &&
+            !(await configurationExists(configPath));
+        if (!useAutomaticConfiguration)
+            throw error;
+        configuration = await automaticConfiguration();
+    }
     const resolver = await WorkspaceResolver.create(configuration);
     const engine = new CoreEngine(resolver);
     await engine.initialize();