hoi4-agent-tools 3.3.0 → 3.4.1

package/dist/hoi4_agent_tools/probability/operations.js

@@ -21,6 +21,9 @@ export function probabilityAnalysisData(result) {
         cacheKey: result.metadata.cacheKey,
         scenarios: result.scenarios.length,
         candidates: result.scenarios.reduce((sum, scenario) => sum + scenario.candidates.length, 0),
+        eligibleCandidates: result.scenarios.reduce((sum, scenario) => sum + scenario.candidates.filter(({ eligibility }) => eligibility === 'true').length, 0),
+        excludedCandidates: result.scenarios.reduce((sum, scenario) => sum + scenario.candidates.filter(({ eligibility }) => eligibility === 'false').length, 0),
+        unresolvedCandidates: result.scenarios.reduce((sum, scenario) => sum + scenario.candidates.filter(({ eligibility }) => eligibility === 'unresolved').length, 0),
         ...(result.scenarios.some(({ scopePools }) => (scopePools?.length ?? 0) > 0)
             ? {
                 scopePools: result.scenarios.reduce((sum, scenario) => sum + (scenario.scopePools?.length ?? 0), 0),
@@ -87,6 +90,8 @@ export function normalizeProbabilityRenderRequest(input) {
 }
 export async function inspectProbabilities(analyzer, input, context) {
     const inspected = await analyzer.inspect(runtime(context, input.refresh), input.adapter, input.source, input.candidatePool, input.customPoolManifest);
+    const sourceRequiredInputPaths = (inspected.surface?.requiredInputs ?? []).filter((path) => path !== 'focus.external_factors_complete' && path !== 'technology.external_factors_complete');
+    const adapterRequiredInputPaths = (inspected.surface?.requiredInputs ?? []).filter((path) => path === 'focus.external_factors_complete' || path === 'technology.external_factors_complete');
     const result = emptyServiceResult(context.workspaceId, {
         adapters: inspected.adapters.length,
         ...(inspected.surface === undefined
@@ -120,6 +125,9 @@ export async function inspectProbabilities(analyzer, input, context) {
         })) ?? [],
         candidateExamples: inspected.discovery?.exampleCandidateIds ?? [],
         requiredInputs: inspected.surface?.requiredInputs.length ?? 0,
+        requiredInputPaths: sourceRequiredInputPaths.slice(0, 32),
+        requiredInputPathsTruncated: sourceRequiredInputPaths.length > 32,
+        adapterRequiredInputPaths,
         unresolved: inspected.surface?.unsupported.length ?? 0,
     });
     result.code =

package/dist/hoi4_agent_tools/probability/service.js

@@ -9,7 +9,7 @@ import { PACKAGE_VERSION } from '../version.js';
 import { probabilityAnalysisResultSchema } from '../schemas/probability.js';
 import { probabilityAdapter, probabilityAdapters } from './adapters.js';
 import { compareProbabilityResults } from './compare.js';
-import { evaluateExactCandidates, evaluateSurfaceScenarios } from './evaluation.js';
+import { evaluateExactCandidates, evaluateSurfaceScenarios, } from './evaluation.js';
 import { VERIFIED_GAME_CHECKSUM, VERIFIED_GAME_RAW_VERSION, VERIFIED_GAME_VERSION, } from './model.js';
 import { renderProbabilityResult } from './render.js';
 import { analyzeSequence, evaluateCustomPoolPoint } from './sequence.js';
@@ -17,6 +17,28 @@ import { simulateSurface } from './simulation.js';
 import { Rational } from './rational.js';
 import { discoverWeightedSurface, inventoryWeightedSurfaces, } from './source-analysis.js';
 import { sweepSurface } from './sweep.js';
+function missingScenarioInputs(unresolved) {
+    return [
+        ...new Set(unresolved.flatMap(({ code, path, details }) => {
+            if (typeof details?.scenarioInput === 'string')
+                return [details.scenarioInput];
+            if (code === 'VALUE_UNRESOLVED' && path !== undefined && !/^(?:@|constant:)/u.test(path))
+                return [path];
+            if (path !== undefined &&
+                (code === 'FOCUS_EXTERNAL_FACTORS_UNDECLARED' ||
+                    code === 'TECHNOLOGY_EXTERNAL_FACTORS_UNDECLARED'))
+                return [path];
+            return [];
+        })),
+    ].sort(compareCodeUnits);
+}
+function blockingInspectionUnresolved(candidate) {
+    if (candidate.eligibility === 'false')
+        return [];
+    if (candidate.eligibility === 'unresolved')
+        return [...candidate.eligibilityUnresolved, ...candidate.externalUnresolved];
+    return [...candidate.valueUnresolved, ...candidate.externalUnresolved];
+}
 const states = new WeakMap();
 const ANALYSIS_CACHE_ENTRIES = 16;
 function resolveSourceBackedAdapter(snapshot, source, candidatePool, requested) {
@@ -1063,9 +1085,7 @@ export class ProbabilityAnalyzer {
         }
         const definitions = ClausewitzEvaluationDefinitions.build(snapshot);
         const inspectedCandidates = evaluateExactCandidates(surface, { id: 'inspection', state: {} }, definitions);
-        const requiredInputs = [
-            ...new Set(inspectedCandidates.flatMap(({ unresolved }) => unresolved.flatMap(({ path }) => (path === undefined ? [] : [path])))),
-        ].sort();
+        const requiredInputs = missingScenarioInputs(inspectedCandidates.flatMap(blockingInspectionUnresolved));
         const report = {
             schemaVersion: 'probability-inspection.v2',
             workspaceId: context.workspaceId,
@@ -1079,9 +1099,8 @@ export class ProbabilityAnalyzer {
                 candidateCount: surface.candidates.length,
                 candidates: surface.candidates.map((candidate, index) => {
                     const evaluated = inspectedCandidates[index];
-                    const candidateRequiredInputs = [
-                        ...new Set(evaluated.unresolved.flatMap(({ path }) => (path === undefined ? [] : [path]))),
-                    ].sort();
+                    const blockingUnresolved = blockingInspectionUnresolved(evaluated);
+                    const candidateRequiredInputs = missingScenarioInputs(blockingUnresolved);
                     return {
                         id: candidate.id,
                         sourceKind: candidate.sourceKind,
@@ -1092,11 +1111,13 @@ export class ProbabilityAnalyzer {
                         referencedProvenance: evaluated.provenance.filter(({ path, symbol }) => !candidate.provenance.some((source) => source.path === path && source.symbol === symbol)),
                         analysisSupport: candidateRequiredInputs.length > 0
                             ? 'requires_scenario'
-                            : surface.adapter.selectionRule === 'score_only'
-                                ? 'score_only'
-                                : surface.adapter.completePoolRequired && !surface.poolComplete
-                                    ? 'requires_complete_pool'
-                                    : 'exact',
+                            : blockingUnresolved.length > 0
+                                ? 'unresolved_source'
+                                : surface.adapter.selectionRule === 'score_only'
+                                    ? 'score_only'
+                                    : surface.adapter.completePoolRequired && !surface.poolComplete
+                                        ? 'requires_complete_pool'
+                                        : 'exact',
                     };
                 }),
                 requiredInputs,

package/dist/hoi4_agent_tools/probability/source-analysis.js

@@ -421,6 +421,7 @@ export function inventoryWeightedSurfaces(snapshot, source, candidatePool = [],
                 ? candidates.length
                 : candidates.filter(({ id }) => wanted.has(id)).length,
             exampleCandidateIds: [...new Set(candidates.map(({ id }) => id))].slice(0, 10),
+            candidateCatalog: candidates.map(({ id, provenance }) => ({ id, provenance })),
             sourcePaths: [
                 ...new Set(candidates.flatMap(({ provenance }) => provenance.map(({ path }) => path))),
             ].sort(compareCodeUnits),

package/dist/hoi4_agent_tools/schemas/event.js

@@ -151,6 +151,12 @@ export function validateEventCompareRequest(value, context) {
             path: ['after'],
             message: 'after and proposedSources are mutually exclusive',
         });
+    if (value.maxChainNodes !== undefined && value.selector === undefined)
+        context.addIssue({
+            code: 'custom',
+            path: ['maxChainNodes'],
+            message: 'maxChainNodes requires selector',
+        });
 }
 export const eventCompareRequestSchema = z
     .object({
@@ -158,6 +164,8 @@ export const eventCompareRequestSchema = z
     before: eventGraphReferenceSchema.optional(),
     after: eventGraphReferenceSchema.optional(),
     proposedSources: z.array(eventProposedSourceSchema).min(1).max(64).optional(),
+    selector: eventSelectorSchema.optional(),
+    maxChainNodes: z.number().int().min(1).max(5_000).optional(),
     render: z.boolean().optional(),
     maxRenderNodes: z.number().int().min(1).max(240).optional(),
     refresh: z.boolean().optional(),

package/dist/hoi4_agent_tools/schemas/focus-requests.js

@@ -17,6 +17,10 @@ export const focusInspectRequestSchema = z
     previous: compactFocusLayoutSchema.optional(),
     laneSpacing: z.number().int().min(1).max(100).optional(),
     nodeSpacing: z.number().int().min(1).max(100).optional(),
+    scenario: z
+        .object({ completedFocusIds: z.array(z.string().min(1).max(256)).max(10_000) })
+        .strict()
+        .optional(),
 })
     .strict()
     .superRefine((value, context) => {
@@ -34,7 +38,7 @@ export const focusInspectRequestSchema = z
             message: 'treeId is only valid in national mode',
         });
     if (mode === 'continuous') {
-        for (const field of ['previous', 'laneSpacing', 'nodeSpacing']) {
+        for (const field of ['previous', 'laneSpacing', 'nodeSpacing', 'scenario']) {
             if (value[field] !== undefined)
                 context.addIssue({
                     code: 'custom',
@@ -49,6 +53,12 @@ export const focusInspectRequestSchema = z
             path: ['previous'],
             message: 'previous requires treeId so it applies to exactly one tree',
         });
+    if (value.scenario !== undefined && value.treeId === undefined)
+        context.addIssue({
+            code: 'custom',
+            path: ['scenario'],
+            message: 'scenario requires treeId so it applies to exactly one tree',
+        });
 });
 export const focusRenderRequestSchema = z
     .object({
@@ -64,6 +74,7 @@ export const focusRenderRequestSchema = z
         .min(FOCUS_RENDER_MIN_OUTPUT_SCALE)
         .max(FOCUS_RENDER_MAX_OUTPUT_SCALE)
         .optional(),
+    cropFocusIds: z.array(z.string().min(1).max(256)).max(16).optional(),
     columns: z.number().int().min(1).max(12).optional(),
     padding: z.number().int().min(0).max(1000).optional(),
 })
@@ -80,6 +91,7 @@ export const focusRenderRequestSchema = z
             ['horizontalSpacing', value.horizontalSpacing],
             ['verticalSpacing', value.verticalSpacing],
             ['reviewScale', value.reviewScale],
+            ['cropFocusIds', value.cropFocusIds],
         ];
     for (const [field, fieldValue] of invalid) {
         if (fieldValue !== undefined)
@@ -103,6 +115,25 @@ export const focusRewriteRequestSchema = z
     relativePath: workspaceRelativePathSchema,
     treeId: z.string().min(1).max(256).optional(),
     layoutMode: z.enum(['authored', 'compact']).default('authored'),
+    compactFocusIds: z.array(z.string().min(1).max(256)).min(1).max(10_000).optional(),
+    pinnedFocusIds: z.array(z.string().min(1).max(256)).max(10_000).optional(),
+    symmetryGroups: z
+        .array(z
+        .object({
+        centerFocusId: z.string().min(1).max(256),
+        pairs: z
+            .array(z
+            .object({
+            leftFocusId: z.string().min(1).max(256),
+            rightFocusId: z.string().min(1).max(256),
+        })
+            .strict())
+            .min(1)
+            .max(10_000),
+    })
+        .strict())
+        .max(64)
+        .optional(),
     plan: compactFocusPlanSchema.optional(),
     createIfMissing: z.boolean().default(false),
     horizontalSpacing: z.number().int().min(80).max(1000).optional(),
@@ -117,6 +148,14 @@ export const focusRewriteRequestSchema = z
 })
     .strict()
     .superRefine((value, context) => {
+    if (value.layoutMode !== 'compact')
+        for (const field of ['compactFocusIds', 'pinnedFocusIds', 'symmetryGroups'])
+            if (value[field] !== undefined)
+                context.addIssue({
+                    code: 'custom',
+                    path: [field],
+                    message: `${field} requires compact layout mode`,
+                });
     const mode = value.mode ?? 'national';
     const schema = mode === 'continuous' ? continuousFocusPaletteSchema : focusTreePlanSchema;
     if (value.plan !== undefined && !schema.safeParse(value.plan).success)

package/dist/hoi4_agent_tools/schemas/gui-requests.js

@@ -82,6 +82,14 @@ export const guiRenderRequestSchema = z
     relatedScenarios: z.array(compactGuiScenarioSchema).max(32).optional(),
     generatedScenarios: compactGeneratedScenarioOptionsSchema.optional(),
     comparisonScenario: compactGuiScenarioSchema.optional(),
+    sourceBaseline: z
+        .object({
+        relativePath: workspaceRelativePathSchema,
+        source: z.string().max(SOURCE_MAX_BYTES),
+    })
+        .strict()
+        .optional()
+        .describe('Previous mod-owned .gui source for a matched source comparison using the requested scenario.'),
 })
     .strict()
     .superRefine(({ scenario, states, resolutions, relatedScenarios, generatedScenarios }, context) => {

package/dist/hoi4_agent_tools/schemas/map-requests.js

@@ -63,6 +63,7 @@ export const mapInspectRequestSchema = z
     ]))
         .max(100)
         .default([]),
+    lookupOnly: z.boolean().default(false),
     includeOverview: z.boolean().default(true),
     allocationRequests: z.array(mapAllocationRequestSchema).max(100).default([]),
 })
@@ -73,8 +74,28 @@ export const mapRenderRequestSchema = z
     layer: mapLayerSchema.optional(),
     overlays: z.array(mapOverlaySchema).max(12).optional(),
     scale: z.number().int().min(1).max(16).optional(),
+    tile: z
+        .object({
+        x: z.number().int().min(0),
+        y: z.number().int().min(0),
+        width: z.number().int().min(1).max(2_048),
+        height: z.number().int().min(1).max(2_048),
+    })
+        .strict()
+        .optional(),
+    area: z
+        .object({
+        provinceIds: z.array(z.number().int().nonnegative()).max(256).optional(),
+        stateIds: z.array(z.number().int().nonnegative()).max(64).optional(),
+        regionIds: z.array(z.number().int().nonnegative()).max(64).optional(),
+        padding: z.number().int().min(0).max(256).optional(),
+    })
+        .strict()
+        .refine(({ provinceIds, stateIds, regionIds }) => (provinceIds?.length ?? 0) + (stateIds?.length ?? 0) + (regionIds?.length ?? 0) > 0, 'Map area requires at least one province, state, or region ID')
+        .optional(),
 })
-    .strict();
+    .strict()
+    .refine(({ tile, area }) => tile === undefined || area === undefined, 'Choose tile or area, not both');
 export const mapRewriteRequestSchema = z
     .object({
     workspaceId: workspaceIdSchema,

package/dist/hoi4_agent_tools/schemas/technology.js

@@ -132,6 +132,13 @@ export const technologyRenderRequestSchema = z
     categoryId: technologyIdSchema.optional(),
     targetId: technologyIdSchema.optional(),
     maxNodes: z.number().int().min(1).max(2_000).optional(),
+    scenario: z
+        .object({
+        year: z.number().int().min(1).max(9999),
+        researchedTechnologyIds: z.array(technologyIdSchema).max(25_000),
+    })
+        .strict()
+        .optional(),
     includeHtml: z.boolean().optional(),
     refresh: z.boolean().optional(),
 })

package/dist/hoi4_agent_tools/technology/graph.js

@@ -11,6 +11,7 @@ const MAX_EXTERNAL_REFERENCES = 1_000_000;
 const MAX_ISSUES = 100_000;
 const MAX_HELPER_DEPTH = 64;
 const MAX_HELPER_PROJECTIONS = 500_000;
+const MAX_FULL_HELPER_CALLS = 4_096;
 const confidenceRank = {
     confirmed: 0,
     high: 1,
@@ -188,6 +189,20 @@ function activeYearMarkers(values) {
         left.year - right.year ||
         compareCodeUnits(left.name, right.name));
 }
+function activeBackgrounds(values) {
+    const groups = new Map();
+    for (const background of values) {
+        const key = `${background.folderId}\0${background.name}`;
+        const group = groups.get(key) ?? [];
+        group.push(background);
+        groups.set(key, group);
+    }
+    return [...groups.values()]
+        .map((group) => group.sort((left, right) => right.loadOrder - left.loadOrder ||
+        compareCodeUnits(left.sourcePath, right.sourcePath) ||
+        left.location.start.offset - right.location.start.offset)[0])
+        .sort((left, right) => compareCodeUnits(left.folderId, right.folderId) || compareCodeUnits(left.name, right.name));
+}
 function enrichPlacements(placements, edges, gridboxes, technologies, unlocks, itemLayouts, signal) {
     const technologyById = new Map(technologies.map((technology) => [technology.id, technology]));
     const unlockKindsByTechnology = new Map();
@@ -238,11 +253,8 @@ function enrichPlacements(placements, edges, gridboxes, technologies, unlocks, i
     return placements.map((placement) => {
         const roots = rootsFor(placement.technologyId, placement.folderId);
         const branchRootId = roots.length === 1 ? roots[0] : undefined;
-        const expectedGridbox = branchRootId === undefined ? undefined : `${branchRootId}_tree`;
-        const candidates = expectedGridbox === undefined
-            ? []
-            : gridboxes.filter(({ name, folderId }) => name === expectedGridbox &&
-                (folderId === undefined || folderId === placement.folderId));
+        const expectedGridbox = `${branchRootId ?? placement.technologyId}_tree`;
+        const candidates = gridboxes.filter(({ name, folderId }) => name === expectedGridbox && (folderId === undefined || folderId === placement.folderId));
         const gridbox = candidates[0];
         const technology = technologyById.get(placement.technologyId);
         const folderLayouts = layoutsByFolder.get(placement.folderId);
@@ -1155,6 +1167,7 @@ function* technologyGraphAnalysis(snapshot, options) {
     const gridboxes = activeGridboxes(fragments.flatMap(({ gridboxes }) => gridboxes));
     const itemLayouts = activeItemLayouts(fragments.flatMap(({ itemLayouts }) => itemLayouts));
     const yearMarkers = activeYearMarkers(fragments.flatMap(({ yearMarkers }) => yearMarkers));
+    const backgrounds = activeBackgrounds(fragments.flatMap(({ backgrounds }) => backgrounds ?? []));
     const categories = activeCategories(fragments.flatMap(({ categories }) => categories));
     const selectedDoctrines = activeDefinitions(fragments.flatMap(({ doctrineDefinitions }) => doctrineDefinitions));
     const doctrineDefinitions = localiseDoctrines(selectedDoctrines.active, snapshot.index, assets);
@@ -1168,10 +1181,11 @@ function* technologyGraphAnalysis(snapshot, options) {
     const placements = enrichPlacements(basePlacements, edges, gridboxes, technologies, unlocks, itemLayouts, options.signal);
     const unresolved = fragments.flatMap(({ unresolved }) => unresolved);
     const helperCalls = fragments.flatMap(({ helperCalls }) => helperCalls);
-    const walk = options.analysisMode === 'focused'
+    const analysisMode = options.analysisMode ?? (helperCalls.length > MAX_FULL_HELPER_CALLS ? 'focused' : 'full');
+    const walk = analysisMode === 'focused'
         ? undefined
         : yield technologyHelperWalk(helperCalls, snapshot.revision);
-    const externalReferences = expandHelperReferences(fragments.flatMap(({ externalReferences }) => externalReferences), helperCalls, unresolved, options.analysisMode ?? 'full', walk, options.signal);
+    const externalReferences = expandHelperReferences(fragments.flatMap(({ externalReferences }) => externalReferences), helperCalls, unresolved, analysisMode, walk, options.signal);
     const issues = diagnose(technologies, folders, placements, gridboxes, edges, categories, doctrineDefinitions, unlocks, externalReferences, selectedTechnologies.duplicates.map((group) => group.map(({ iconSprite, effectSignatureFields, ...technology }) => ({
         ...technology,
         icon: iconStatus(iconSprite, snapshot.index, assets),
@@ -1197,14 +1211,14 @@ function* technologyGraphAnalysis(snapshot, options) {
     const graph = {
         schemaVersion: TECHNOLOGY_GRAPH_SCHEMA_VERSION,
         parserVersion: TECHNOLOGY_PARSER_VERSION,
-        analysisMode: options.analysisMode ?? 'full',
+        analysisMode,
         workspaceId: snapshot.workspaceId,
         workspaceIdentity: options.workspaceIdentity,
         revision,
         complete: snapshot.complete &&
             unresolved.every(({ kind }) => kind !== 'partial_source') &&
             !unresolved.some(({ blockers }) => blockers.some(({ code }) => code === 'TECH_HELPER_DEPTH_BLOCKED' || code === 'TECH_HELPER_PROJECTION_LIMIT')) &&
-            !(options.analysisMode === 'focused' && helperCalls.length > 0),
+            !(analysisMode === 'focused' && helperCalls.length > 0),
         analysisBoundary: {
             staticAnalysis: true,
             language: 'l_english',
@@ -1215,7 +1229,7 @@ function* technologyGraphAnalysis(snapshot, options) {
                 'meta-generated or variable technology identifiers',
                 'exact AI research choice and runtime research time',
                 'dynamic scripted localisation without supplied runtime values',
-                ...(options.analysisMode === 'focused' && helperCalls.length > 0
+                ...(analysisMode === 'focused' && helperCalls.length > 0
                     ? ['large-workspace scripted-effect helper projections are deferred']
                     : []),
             ],
@@ -1235,6 +1249,7 @@ function* technologyGraphAnalysis(snapshot, options) {
         gridboxes,
         itemLayouts,
         yearMarkers,
+        backgrounds,
         edges,
         categories,
         doctrineDefinitions,

package/dist/hoi4_agent_tools/technology/operations.js

@@ -58,6 +58,34 @@ export function technologyValidation(graph) {
         ],
     };
 }
+export function technologyRenderValidation(graph, render) {
+    const omitted = render.omittedNodeCount;
+    const unresolvedSprites = render.unresolvedIconSprites.length;
+    const sourcePlacementPassed = render.view !== 'folder' || render.sourceAccurate;
+    const analysisBoundaryPassed = graph.complete || (graph.analysisMode === 'focused' && graph.skippedSourceCount === 0);
+    const renderPassed = sourcePlacementPassed && omitted === 0 && unresolvedSprites === 0;
+    return {
+        passed: renderPassed && analysisBoundaryPassed,
+        checks: [
+            {
+                id: 'technology-render',
+                passed: renderPassed,
+                message: renderPassed
+                    ? 'The requested technology view rendered with complete node and sprite coverage'
+                    : `${sourcePlacementPassed ? 0 : 1} source-placement failure(s), ${omitted} omitted node(s), and ${unresolvedSprites} unresolved sprite(s) affect the requested technology view`,
+            },
+            {
+                id: 'technology-analysis-boundary',
+                passed: analysisBoundaryPassed,
+                message: graph.complete
+                    ? 'The supporting technology analysis is complete'
+                    : analysisBoundaryPassed
+                        ? 'Whole-workspace helper projections were deferred; the requested render retains direct source evidence'
+                        : `${graph.skippedSourceCount} technology source(s) were skipped; linked evidence records the partial analysis boundary`,
+            },
+        ],
+    };
+}
 export async function inspectTechnologies(viewer, input) {
     const output = await viewer.analyze(input);
     const result = emptyServiceResult(input.workspaceId, {
@@ -93,7 +121,7 @@ export async function renderTechnologies(viewer, input) {
     result.code = output.graph.complete ? 'TECH_RENDERED' : 'TECH_RENDERED_PARTIAL';
     setInlineFilesScanned(result, output.graph.filesScanned);
     result.artifacts = output.artifacts.map(publicArtifactLink);
-    result.validation = technologyValidation(output.graph);
+    result.validation = technologyRenderValidation(output.graph, output.render);
     return result;
 }
 export async function compareTechnologies(viewer, input) {