hoi4-agent-tools 2.0.0 → 2.1.0

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

@@ -1,12 +1,11 @@
 import { z } from 'zod/v4';
 import { boundedSourceHashEvidence, publicArtifactLink } from '../../core/artifacts.js';
-import { compareCodeUnits, canonicalJson, sha256Bytes } from '../../core/canonical.js';
-import { comparePngImages, createTransparentPng } from '../../core/image-diff.js';
+import { compareCodeUnits, canonicalJson } from '../../core/canonical.js';
 import { RenderBudget } from '../../core/render-budget.js';
 import { emptyServiceResult, ServiceError } from '../../core/result.js';
 import { parseClausewitz } from '../../core/source/index.js';
 import { readDependenciesFromScannedFiles } from '../../core/transactions.js';
-import { FocusWorkbench, FOCUS_RENDER_MAX_OUTPUT_SCALE, FOCUS_RENDER_MIN_OUTPUT_SCALE, assertCompactLayoutQuality, compactFocusTreePlanAsync, focusPlanHash, focusPresentationEvidence, focusPlanningSidecarPath, importContinuousFocusPalettes, importFocusTrees, linkContinuousFocusPalettes, parseFocusPlanningSidecar, renderContinuousFocusPalette, renderFocusTree, resolveFocusPresentation, enrichFocusPlanFromSidecar, } from '../../focus/index.js';
+import { FocusWorkbench, FOCUS_RENDER_MAX_OUTPUT_SCALE, FOCUS_RENDER_MIN_OUTPUT_SCALE, assertCompactLayoutQuality, compactFocusTreePlanAsync, focusPlanHash, focusPresentationEvidence, focusPlanningSidecarPath, importContinuousFocusPalettes, importFocusTrees, linkContinuousFocusPalettes, parseFocusPlanningSidecar, resolveFocusPresentation, enrichFocusPlanFromSidecar, } from '../../focus/index.js';
 import { continuousFocusPaletteSchema, focusLayoutMetricsSchema, focusLayoutSchema, focusTreePlanSchema, } from '../../schemas/focus.js';
 import { workspaceIdSchema, workspaceRelativePathSchema } from '../../schemas/common.js';
 import { PACKAGE_VERSION } from '../../version.js';
@@ -308,6 +307,124 @@ const LARGE_FOCUS_RENDER_SCALE = 0.5;
 function automaticFocusRenderScale(focusCount) {
     return focusCount >= LARGE_FOCUS_RENDER_NODE_THRESHOLD ? LARGE_FOCUS_RENDER_SCALE : 1;
 }
+async function executeFocusVisualTool(engine, workbench, context, input, extra, rasterize) {
+    const { workspaceId: requestedWorkspaceId, relativePath } = input;
+    const workspaceId = engine.resolver.resolveWorkspaceId(requestedWorkspaceId, context.principal);
+    const outputName = rasterize ? 'raster' : 'render';
+    try {
+        const progress = progressReporter(extra);
+        await progress.report(0, 4, 'Importing and indexing focus source');
+        const snapshot = await engine.scan(workspaceId, {}, context.principal, progress.signal);
+        await progress.report(1, 4, 'Focus source index complete');
+        const workspace = engine.resolver.get(workspaceId, context.principal);
+        const renderBudget = new RenderBudget();
+        if (input.mode === 'continuous') {
+            selectedContinuousFocusFile(snapshot, relativePath);
+            const imported = await workbench.importContinuousPath(workspaceId, relativePath, context.principal);
+            const plan = selectContinuousPlan(imported.result, input.paletteId);
+            const presentation = await resolveFocusPresentation({
+                plans: [],
+                palettes: [plan],
+                files: snapshot.files,
+                index: snapshot.index,
+                scanner: engine.scanner,
+                workspace,
+                decodeIcons: rasterize,
+                budget: renderBudget,
+                signal: progress.signal,
+            });
+            await progress.report(2, 4, `Producing continuous focus ${outputName} artifacts`);
+            const rendered = await workbench.renderContinuousAndStore(workspaceId, plan, {
+                ...(context.principal === undefined ? {} : { principal: context.principal }),
+                presentation,
+                sourceHashes: presentation.sourceHashes,
+                ...(input.columns === undefined ? {} : { columns: input.columns }),
+                ...(input.padding === undefined ? {} : { padding: input.padding }),
+                renderProfile: { sourceRevision: snapshot.revision, output: outputName },
+                rasterize,
+                budget: renderBudget,
+                signal: progress.signal,
+            });
+            const diagnostics = [...imported.result.diagnostics, ...rendered.diagnostics];
+            const result = emptyServiceResult(workspaceId, {
+                mode: 'continuous',
+                paletteId: plan.id,
+                focusCount: plan.focuses.length,
+                hashes: rendered.bundle.hashes,
+                width: rendered.bundle.width,
+                height: rendered.bundle.height,
+            });
+            result.code = rasterize ? 'CONTINUOUS_FOCUS_RASTERIZED' : 'CONTINUOUS_FOCUS_RENDERED';
+            setInlineFilesScanned(result, [...new Set([plan.provenance.sourcePath, ...presentation.filesScanned])].sort((left, right) => compareCodeUnits(left, right)));
+            result.diagnostics = diagnostics.slice(0, 100);
+            result.artifacts = rendered.artifacts.map(publicArtifactLink);
+            result.validation = validationFromDiagnostics(diagnostics);
+            await progress.report(4, 4, `Continuous focus ${outputName} complete`);
+            return toolResult(result);
+        }
+        const paletteImport = continuousPalettes(snapshot);
+        const imported = importFocusFile(snapshot, selectedFocusFile(snapshot, workspace.registration.roots.focus, relativePath), paletteImport.palettes);
+        const plan = selectPlan(imported, input.treeId);
+        const linkedPalettes = paletteImport.palettes.filter(({ id }) => plan.continuousFocusPaletteIds.includes(id));
+        const presentation = await resolveFocusPresentation({
+            plans: [plan],
+            palettes: linkedPalettes,
+            files: snapshot.files,
+            index: snapshot.index,
+            scanner: engine.scanner,
+            workspace,
+            decodeIcons: rasterize,
+            budget: renderBudget,
+            signal: progress.signal,
+        });
+        await progress.report(2, 4, `Producing focus ${outputName} artifacts`);
+        const effectiveReviewScale = input.reviewScale ?? automaticFocusRenderScale(plan.focuses.length);
+        const rendered = await workbench.renderAndStore(workspaceId, plan, {
+            ...(context.principal === undefined ? {} : { principal: context.principal }),
+            index: snapshot.index,
+            references: referenceCatalog(snapshot),
+            presentation,
+            sourceHashes: presentation.sourceHashes,
+            ...(input.horizontalSpacing === undefined
+                ? {}
+                : { horizontalSpacing: input.horizontalSpacing }),
+            ...(input.verticalSpacing === undefined ? {} : { verticalSpacing: input.verticalSpacing }),
+            ...(input.padding === undefined ? {} : { padding: input.padding }),
+            outputScale: effectiveReviewScale,
+            rasterize,
+            renderProfile: {
+                sourceRevision: snapshot.revision,
+                reviewScale: effectiveReviewScale,
+                output: outputName,
+            },
+            budget: renderBudget,
+            signal: progress.signal,
+        });
+        const diagnostics = [
+            ...paletteImport.diagnostics,
+            ...imported.diagnostics,
+            ...rendered.diagnostics,
+        ];
+        const result = emptyServiceResult(workspaceId, {
+            mode: 'national',
+            treeId: plan.id,
+            layoutHash: rendered.layout.layoutHash,
+            hashes: rendered.bundle.hashes,
+            width: rendered.bundle.width,
+            height: rendered.bundle.height,
+        });
+        result.code = rasterize ? 'FOCUS_RASTERIZED' : 'FOCUS_RENDERED';
+        setInlineFilesScanned(result, [...new Set([plan.provenance.sourcePath, ...presentation.filesScanned])].sort((left, right) => compareCodeUnits(left, right)));
+        result.diagnostics = diagnostics.slice(0, 100);
+        result.artifacts = rendered.artifacts.map(publicArtifactLink);
+        result.validation = validationFromDiagnostics(diagnostics);
+        await progress.report(4, 4, `Focus ${outputName} complete`);
+        return toolResult(result);
+    }
+    catch (error) {
+        return errorResult(error, workspaceId);
+    }
+}
 function compactDrift(drift) {
     return {
         status: drift.status,
@@ -490,6 +607,7 @@ export function registerFocusTools(server, engine, context) {
                     index: snapshot.index,
                     scanner: engine.scanner,
                     workspace,
+                    decodeIcons: false,
                     signal: progress.signal,
                 });
                 diagnostics.push(...presentation.diagnostics);
@@ -589,6 +707,7 @@ export function registerFocusTools(server, engine, context) {
                 index: snapshot.index,
                 scanner: engine.scanner,
                 workspace,
+                decodeIcons: false,
                 signal: progress.signal,
             });
             diagnostics.push(...presentation.diagnostics);
@@ -663,123 +782,18 @@ export function registerFocusTools(server, engine, context) {
     });
     server.registerTool('hoi4.focus_render', {
         title: 'Render focus review artifacts',
-        description: 'Render a national tree or continuous palette for creation and cleanup review as deterministic HTML, SVG, PNG, JSON, and source-map artifacts. Omit mode for national behavior. National trees with at least 200 focuses use reviewScale 0.5 by default; set 0.25 through 1.0 explicitly when needed.',
+        description: 'Render a national tree or continuous palette as fast deterministic HTML, SVG, JSON, and source-map artifacts. Use hoi4.focus_raster when decoded icons and PNG output are needed.',
         inputSchema: focusRenderInput,
         outputSchema: focusRenderOutputSchema,
         annotations: artifactProducing,
-    }, async (input, extra) => {
-        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');
-            const snapshot = await engine.scan(workspaceId, {}, context.principal, progress.signal);
-            const workspace = engine.resolver.get(workspaceId, context.principal);
-            const renderBudget = new RenderBudget();
-            if (input.mode === 'continuous') {
-                selectedContinuousFocusFile(snapshot, relativePath);
-                const imported = await workbench.importContinuousPath(workspaceId, relativePath, context.principal);
-                const plan = selectContinuousPlan(imported.result, input.paletteId);
-                const presentation = await resolveFocusPresentation({
-                    plans: [],
-                    palettes: [plan],
-                    files: snapshot.files,
-                    index: snapshot.index,
-                    scanner: engine.scanner,
-                    workspace,
-                    budget: renderBudget,
-                    signal: progress.signal,
-                });
-                await progress.report(1, 3, 'Rendering continuous focus artifacts');
-                const rendered = await workbench.renderContinuousAndStore(workspaceId, plan, {
-                    ...(context.principal === undefined ? {} : { principal: context.principal }),
-                    presentation,
-                    sourceHashes: presentation.sourceHashes,
-                    ...(input.columns === undefined ? {} : { columns: input.columns }),
-                    ...(input.padding === undefined ? {} : { padding: input.padding }),
-                    renderProfile: { sourceRevision: snapshot.revision },
-                    budget: renderBudget,
-                    signal: progress.signal,
-                });
-                const diagnostics = [...imported.result.diagnostics, ...rendered.diagnostics];
-                const result = emptyServiceResult(workspaceId, {
-                    mode: 'continuous',
-                    paletteId: plan.id,
-                    focusCount: plan.focuses.length,
-                    hashes: rendered.bundle.hashes,
-                    width: rendered.bundle.width,
-                    height: rendered.bundle.height,
-                });
-                result.code = 'CONTINUOUS_FOCUS_RENDERED';
-                setInlineFilesScanned(result, [...new Set([plan.provenance.sourcePath, ...presentation.filesScanned])].sort((left, right) => compareCodeUnits(left, right)));
-                result.diagnostics = diagnostics.slice(0, 100);
-                result.artifacts = rendered.artifacts.map(publicArtifactLink);
-                result.validation = validationFromDiagnostics(diagnostics);
-                await progress.report(3, 3, 'Continuous focus render complete');
-                return toolResult(result);
-            }
-            const paletteImport = continuousPalettes(snapshot);
-            const imported = importFocusFile(snapshot, selectedFocusFile(snapshot, workspace.registration.roots.focus, relativePath), paletteImport.palettes);
-            const plan = selectPlan(imported, input.treeId);
-            const linkedPalettes = paletteImport.palettes.filter(({ id }) => plan.continuousFocusPaletteIds.includes(id));
-            const presentation = await resolveFocusPresentation({
-                plans: [plan],
-                palettes: linkedPalettes,
-                files: snapshot.files,
-                index: snapshot.index,
-                scanner: engine.scanner,
-                workspace,
-                budget: renderBudget,
-                signal: progress.signal,
-            });
-            await progress.report(1, 3, 'Rendering focus artifacts');
-            const effectiveReviewScale = input.reviewScale ?? automaticFocusRenderScale(plan.focuses.length);
-            const rendered = await workbench.renderAndStore(workspaceId, plan, {
-                ...(context.principal === undefined ? {} : { principal: context.principal }),
-                index: snapshot.index,
-                references: referenceCatalog(snapshot),
-                presentation,
-                sourceHashes: presentation.sourceHashes,
-                ...(input.horizontalSpacing === undefined
-                    ? {}
-                    : { horizontalSpacing: input.horizontalSpacing }),
-                ...(input.verticalSpacing === undefined
-                    ? {}
-                    : { verticalSpacing: input.verticalSpacing }),
-                ...(input.padding === undefined ? {} : { padding: input.padding }),
-                outputScale: effectiveReviewScale,
-                renderProfile: {
-                    sourceRevision: snapshot.revision,
-                    reviewScale: effectiveReviewScale,
-                },
-                budget: renderBudget,
-                signal: progress.signal,
-            });
-            const diagnostics = [
-                ...paletteImport.diagnostics,
-                ...imported.diagnostics,
-                ...rendered.diagnostics,
-            ];
-            const result = emptyServiceResult(workspaceId, {
-                mode: 'national',
-                treeId: plan.id,
-                layoutHash: rendered.layout.layoutHash,
-                hashes: rendered.bundle.hashes,
-                width: rendered.bundle.width,
-                height: rendered.bundle.height,
-            });
-            result.code = 'FOCUS_RENDERED';
-            setInlineFilesScanned(result, [...new Set([plan.provenance.sourcePath, ...presentation.filesScanned])].sort((left, right) => compareCodeUnits(left, right)));
-            result.diagnostics = diagnostics.slice(0, 100);
-            result.artifacts = rendered.artifacts.map(publicArtifactLink);
-            result.validation = validationFromDiagnostics(diagnostics);
-            await progress.report(3, 3, 'Focus render complete');
-            return toolResult(result);
-        }
-        catch (error) {
-            return errorResult(error, workspaceId);
-        }
-    });
+    }, (input, extra) => executeFocusVisualTool(engine, workbench, context, input, extra, false));
+    server.registerTool('hoi4.focus_raster', {
+        title: 'Rasterize focus review artifacts',
+        description: 'Produce the high-fidelity focus review with decoded source icons and deterministic PNG output. Use focus_render for the faster structural HTML, SVG, and JSON view.',
+        inputSchema: focusRenderInput,
+        outputSchema: focusRenderOutputSchema,
+        annotations: artifactProducing,
+    }, (input, extra) => executeFocusVisualTool(engine, workbench, context, input, extra, true));
     server.registerTool('hoi4.focus_rewrite', {
         title: 'Create or clean up focus content',
         description: 'Create or clean up a national tree or continuous palette, validate it, and apply it in one call. Supply a complete plan; set layoutMode compact for automatic arrangement. Existing national trees can omit the plan and use treeId plus layoutMode compact. Set createIfMissing for a new file.',
@@ -831,20 +845,11 @@ export function registerFocusTools(server, engine, context) {
                     index: snapshot.index,
                     scanner: engine.scanner,
                     workspace,
+                    decodeIcons: false,
                     budget: renderBudget,
                     signal: progress.signal,
                 });
-                const currentDiagnostics = currentPlan === undefined
-                    ? []
-                    : [...(imported?.result.diagnostics ?? []), ...workbench.lintContinuous(currentPlan)];
-                await progress.report(1, 5, 'Rendering before and proposed continuous focus plans');
-                const currentRender = currentPlan === undefined
-                    ? undefined
-                    : await renderContinuousFocusPalette(currentPlan, currentDiagnostics, {
-                        presentation,
-                        signal: progress.signal,
-                        budget: renderBudget,
-                    });
+                await progress.report(1, 5, 'Building proposed continuous focus review');
                 const proposedPlanHash = focusPlanHash(plan);
                 const reviewPlan = {
                     ...plan,
@@ -858,47 +863,16 @@ export function registerFocusTools(server, engine, context) {
                     ...(context.principal === undefined ? {} : { principal: context.principal }),
                     presentation,
                     sourceHashes: presentation.sourceHashes,
-                    renderProfile: { sourceRevision: snapshot.revision, proposedPlanHash },
+                    renderProfile: {
+                        sourceRevision: snapshot.revision,
+                        proposedPlanHash,
+                        output: 'vector',
+                    },
+                    rasterize: false,
                     budget: renderBudget,
                     signal: progress.signal,
                 });
-                const beforePng = currentRender?.png ??
-                    (await createTransparentPng(proposed.bundle.width, proposed.bundle.height, 'new continuous focus baseline', renderBudget));
-                const comparison = await comparePngImages(beforePng, proposed.bundle.png, 8, progress.signal, renderBudget);
-                const stem = plan.id.replace(/[^A-Za-z0-9._-]/gu, '_').slice(0, 80) || 'continuous';
-                const provenance = {
-                    toolVersion: PACKAGE_VERSION,
-                    schemaVersion: 'continuous-focus-visual-diff.v1',
-                    sourceHashes: {
-                        before: sourceFile?.sha256 ?? sha256Bytes(Buffer.alloc(0)),
-                        proposedPlan: proposedPlanHash,
-                    },
-                    renderProfile: { offline: true, kind: 'continuous-focus-palette' },
-                };
-                const comparisonArtifacts = await engine.artifacts.withAtomicWrites(workspace, [
-                    {
-                        name: `${stem}.continuous-focus-before.png`,
-                        mimeType: 'image/png',
-                        content: beforePng,
-                        provenance: { ...provenance, kind: 'continuous-focus-before-render' },
-                    },
-                    {
-                        name: `${stem}.continuous-focus-visual-diff.png`,
-                        mimeType: 'image/png',
-                        content: comparison.png,
-                        provenance: { ...provenance, kind: 'continuous-focus-visual-diff' },
-                    },
-                    {
-                        name: `${stem}.continuous-focus-visual-diff.json`,
-                        mimeType: 'application/json',
-                        content: comparison.json,
-                        provenance: { ...provenance, kind: 'continuous-focus-visual-diff-json' },
-                    },
-                ], (stored) => Promise.resolve([...stored]), progress.signal);
-                const reviewArtifacts = [
-                    ...proposed.artifacts.map(publicArtifactLink),
-                    ...comparisonArtifacts.map(publicArtifactLink),
-                ];
+                const reviewArtifacts = proposed.artifacts.map(publicArtifactLink);
                 await progress.report(3, 5, 'Preparing the continuous focus rewrite');
                 const planned = await workbench.planContinuousChanges({
                     workspaceId,
@@ -1029,6 +1003,7 @@ export function registerFocusTools(server, engine, context) {
                 index: snapshot.index,
                 scanner: engine.scanner,
                 workspace,
+                decodeIcons: false,
                 budget: renderBudget,
                 signal: progress.signal,
             });
@@ -1037,22 +1012,7 @@ export function registerFocusTools(server, engine, context) {
                 : currentPlan === compactSourcePlan && compactPlanning !== undefined
                     ? compactPlanning.currentLayout
                     : await workbench.layoutAsync(currentPlan, { signal: progress.signal });
-            const currentDiagnostics = currentPlan === undefined || currentLayout === undefined
-                ? []
-                : workbench.lint(currentPlan, {
-                    index: snapshot.index,
-                    references: catalog,
-                    layout: currentLayout,
-                });
-            await progress.report(1, 5, 'Rendering before and proposed focus plans');
-            const currentRender = currentPlan === undefined || currentLayout === undefined
-                ? undefined
-                : await renderFocusTree(currentPlan, currentLayout, currentDiagnostics, {
-                    presentation,
-                    ...reviewRenderOptions,
-                    signal: progress.signal,
-                    budget: renderBudget,
-                });
+            await progress.report(1, 5, 'Building proposed focus review');
             const proposedPlanHash = focusPlanHash(plan);
             const reviewPlan = {
                 ...plan,
@@ -1074,56 +1034,18 @@ export function registerFocusTools(server, engine, context) {
                 presentation,
                 sourceHashes: presentation.sourceHashes,
                 ...reviewRenderOptions,
+                rasterize: false,
                 renderProfile: {
                     sourceRevision: snapshot.revision,
                     proposedPlanHash,
                     reviewRenderProfile,
+                    output: 'vector',
                 },
                 budget: renderBudget,
                 signal: progress.signal,
                 layout: proposedLayout,
             });
-            const beforePng = currentRender?.png ??
-                (await createTransparentPng(proposed.bundle.width, proposed.bundle.height, 'new national focus baseline', renderBudget));
-            const comparison = await comparePngImages(beforePng, proposed.bundle.png, 8, progress.signal, renderBudget);
-            const stem = plan.id.replace(/[^A-Za-z0-9._-]/gu, '_').slice(0, 80) || 'focus-tree';
-            const provenance = {
-                toolVersion: PACKAGE_VERSION,
-                schemaVersion: 'focus-visual-diff.v1',
-                sourceHashes: {
-                    before: focusFile?.sha256 ?? sha256Bytes(Buffer.alloc(0)),
-                    proposedPlan: proposedPlanHash,
-                },
-                renderProfile: {
-                    offline: true,
-                    layoutHash: proposed.layout.layoutHash,
-                    reviewRenderProfile,
-                },
-            };
-            const comparisonArtifacts = await engine.artifacts.withAtomicWrites(workspace, [
-                {
-                    name: `${stem}.focus-before.png`,
-                    mimeType: 'image/png',
-                    content: beforePng,
-                    provenance: { ...provenance, kind: 'focus-before-render' },
-                },
-                {
-                    name: `${stem}.focus-visual-diff.png`,
-                    mimeType: 'image/png',
-                    content: comparison.png,
-                    provenance: { ...provenance, kind: 'focus-visual-diff' },
-                },
-                {
-                    name: `${stem}.focus-visual-diff.json`,
-                    mimeType: 'application/json',
-                    content: comparison.json,
-                    provenance: { ...provenance, kind: 'focus-visual-diff-json' },
-                },
-            ], (stored) => Promise.resolve([...stored]), progress.signal);
-            const reviewArtifacts = [
-                ...proposed.artifacts.map(publicArtifactLink),
-                ...comparisonArtifacts.map(publicArtifactLink),
-            ];
+            const reviewArtifacts = proposed.artifacts.map(publicArtifactLink);
             await progress.report(3, 5, 'Preparing the focus-tree rewrite');
             const planned = await workbench.planChanges({
                 workspaceId,

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

@@ -1,10 +1,11 @@
 import { z } from 'zod/v4';
 import { boundedSourceHashEvidence, publicArtifactLink } from '../../core/artifacts.js';
-import { canonicalJson, compareCodeUnits } from '../../core/canonical.js';
+import { canonicalJson, compareCodeUnits, hashCanonical } from '../../core/canonical.js';
 import { renderDimensionViolation, RenderBudget, RENDER_MAX_DIMENSION, } from '../../core/render-budget.js';
 import { emptyServiceResult, ServiceError } from '../../core/result.js';
 import { SOURCE_MAX_BYTES } from '../../core/source/index.js';
 import { GuiHelperDocumentSchema, GuiPreviewScenarioSchema, GUI_TEXT_PACKAGE_MAX_FILES, ScriptedGuiStudio, compileGuiHelpers, } from '../../gui/index.js';
+import { encodeGuiInspectionArtifact, projectGuiGraphForArtifact, } from '../../gui/inspection-artifact.js';
 import { workspaceIdSchema, workspaceRelativePathSchema } from '../../schemas/common.js';
 import { PACKAGE_VERSION } from '../../version.js';
 import { requireServerScope } from '../server/base-tools.js';
@@ -153,7 +154,7 @@ export function registerGuiTools(server, engine, context) {
         const workspaceId = engine.resolver.resolveWorkspaceId(requestedWorkspaceId, context.principal);
         try {
             const progress = progressReporter(extra);
-            await progress.report(0, 3, 'Building shared index and GUI inspection');
+            await progress.report(0, 3, 'Building GUI source graph');
             const inspection = windowName === undefined || scenario === undefined
                 ? studio
                     .scan(workspaceId, context.principal, progress.signal)
@@ -168,18 +169,21 @@ export function registerGuiTools(server, engine, context) {
                     signal: progress.signal,
                 })
                     .then((linted) => ({ graph: linted.graph, linted }));
-            const [shared, inspected] = await Promise.all([
-                engine.scan(workspaceId, {}, context.principal, progress.signal),
-                inspection,
-            ]);
+            const inspected = await inspection;
             const { graph, linted } = inspected;
+            const sharedRevision = hashCanonical(graph.sourceHashes);
             const workspace = engine.resolver.get(workspaceId, context.principal);
             const sourceEvidence = boundedSourceHashEvidence(graph.sourceHashes);
-            const artifact = await engine.artifacts.putChunked(workspace, `gui-inspect.${shared.revision.slice(0, 16)}.json`, 'application/json', `${canonicalJson({
+            const artifactGraph = projectGuiGraphForArtifact(graph, linted?.scene.elements.map(({ sourceId }) => sourceId));
+            const inspectionName = `gui-inspect.${sharedRevision.slice(0, 16)}.json`;
+            const inspectionJson = `${canonicalJson({
                 schemaVersion: 1,
-                sharedRevision: shared.revision,
+                sharedRevision,
                 offline: true,
-                graph,
+                graph: artifactGraph.graph,
+                ...(artifactGraph.projection === undefined
+                    ? {}
+                    : { graphProjection: artifactGraph.projection }),
                 ...(linted === undefined
                     ? {}
                     : {
@@ -187,25 +191,29 @@ export function registerGuiTools(server, engine, context) {
                         fidelity: linted.scene.fidelity,
                         validation: linted.validation,
                     }),
-            })}\n`, {
+            })}\n`;
+            const encodedInspection = await encodeGuiInspectionArtifact(inspectionName, inspectionJson);
+            const artifact = await engine.artifacts.putChunked(workspace, encodedInspection.name, encodedInspection.mimeType, encodedInspection.content, {
                 kind: 'gui-inspect',
                 toolVersion: PACKAGE_VERSION,
                 schemaVersion: 'gui-inspect.v1',
                 sourceHashes: sourceEvidence.sourceHashes,
                 metadata: {
-                    sharedRevision: shared.revision,
+                    sharedRevision,
                     offline: true,
                     complete: graph.complete,
                     skippedSourceCount: graph.skippedSourceCount,
                     sourceHashInventory: sourceEvidence.inventory,
+                    compressed: encodedInspection.compressed,
+                    uncompressedBytes: encodedInspection.uncompressedBytes,
+                    graphProjection: artifactGraph.projection?.mode ?? 'full',
                 },
-            }, 'Scripted GUI graph, diagnostics, and optional scenario fidelity inspection', progress.signal);
-            const diagnostics = [
-                ...shared.diagnostics,
-                ...(linted === undefined ? graph.diagnostics : linted.validation.diagnostics),
-            ];
+            }, encodedInspection.compressed
+                ? 'Gzip-compressed scripted GUI graph, diagnostics, and optional scenario fidelity inspection'
+                : 'Scripted GUI graph, diagnostics, and optional scenario fidelity inspection', progress.signal);
+            const diagnostics = linted === undefined ? graph.diagnostics : linted.validation.diagnostics;
             const result = emptyServiceResult(workspaceId, {
-                sharedRevision: shared.revision,
+                sharedRevision,
                 complete: graph.complete,
                 skippedSourceCount: graph.skippedSourceCount,
                 skippedSources: graph.skippedSources,
@@ -258,9 +266,7 @@ export function registerGuiTools(server, engine, context) {
         const { windowName } = input;
         try {
             const progress = progressReporter(extra);
-            await progress.report(0, 4, 'Building shared index and GUI source graph');
-            const shared = await engine.scan(workspaceId, {}, context.principal, progress.signal);
-            await progress.report(1, 4, 'Rendering offline GUI artifacts');
+            await progress.report(0, 4, 'Building GUI source graph');
             const rendered = await studio.renderAndStore({
                 workspaceId,
                 windowName,
@@ -281,7 +287,8 @@ export function registerGuiTools(server, engine, context) {
                 ...(context.principal === undefined ? {} : { principal: context.principal }),
                 signal: progress.signal,
             });
-            const diagnostics = [...shared.diagnostics, ...rendered.validation.diagnostics];
+            await progress.report(3, 4, 'Preparing GUI result');
+            const diagnostics = rendered.validation.diagnostics;
             const result = emptyServiceResult(workspaceId, {
                 windowName,
                 scenarioId: rendered.render.scene.scenario.id,
@@ -302,7 +309,7 @@ export function registerGuiTools(server, engine, context) {
                 offlineRepresentation: true,
             });
             result.code = code;
-            setInlineFilesScanned(result, shared.files.map(({ displayPath }) => displayPath));
+            setInlineFilesScanned(result, rendered.filesScanned);
             result.diagnostics = diagnostics.slice(0, 100);
             result.artifacts = rendered.artifacts.map(publicArtifactLink);
             result.validation = validationSummary({

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

package/docs/events.md

@@ -2,7 +2,7 @@
 
 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.
+Use the three event tools directly from the target mod.
 
 ## Inspect
 
@@ -16,7 +16,9 @@ Use the three event tools directly; omit `workspaceId` when the MCP working dire
 - `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.
+Use narrow identifiers, direction, and depth limits when the task concerns one chain. Broad scans build the structural event graph without expanding every scripted helper into duplicate paths. Focused trace, path, state, impact, and render calls expand helper relationships when needed.
+
+The compact response summarizes the result. Small scan resources contain the complete graph; very large scan resources contain exact totals, grouped inventories, representative diagnostics, and the revision needed for focused follow-up queries. This keeps an agent's prompt and artifact storage bounded without reducing the results of those focused queries.
 
 Selectors use one of these forms:
 
@@ -37,7 +39,6 @@ Example `hoi4.event_inspect` arguments:
 
 ```json
 {
-  "workspaceId": "my-mod",
   "mode": "trace",
   "selector": { "kind": "event", "eventId": "namespace.1" },
   "direction": "downstream",
@@ -61,7 +62,6 @@ Example `hoi4.event_render` arguments:
 
 ```json
 {
-  "workspaceId": "my-mod",
   "view": "neighborhood",
   "selector": { "kind": "event", "eventId": "namespace.1" },
   "direction": "both",
@@ -83,7 +83,6 @@ Example `hoi4.event_compare` arguments:
 
 ```json
 {
-  "workspaceId": "my-mod",
   "proposedSources": [
     {
       "relativePath": "events/example.txt",