hoi4-agent-tools 3.0.9 → 3.1.0

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

@@ -0,0 +1,189 @@
+import { z } from 'zod/v4';
+import { FOCUS_RENDER_MAX_OUTPUT_SCALE, FOCUS_RENDER_MIN_OUTPUT_SCALE } from '../focus/index.js';
+import { backgroundRequestKeySchema, workspaceIdSchema, workspaceRelativePathSchema, } from './common.js';
+import { continuousFocusPaletteSchema, focusLayoutSchema, focusTreePlanSchema } from './focus.js';
+function compact(schema, description) {
+    return z.unknown().describe(description).pipe(schema);
+}
+const compactFocusLayoutSchema = compact(focusLayoutSchema, 'Prior deterministic focus layout used to stabilize unchanged positions.');
+const compactFocusPlanSchema = compact(z.union([focusTreePlanSchema, continuousFocusPaletteSchema]), 'Complete national or continuous focus plan.');
+export const focusInspectRequestSchema = z
+    .object({
+    mode: z.enum(['national', 'continuous']).optional(),
+    workspaceId: workspaceIdSchema,
+    relativePath: workspaceRelativePathSchema.optional(),
+    treeId: z.string().min(1).max(256).optional(),
+    paletteId: z.string().min(1).max(256).optional(),
+    previous: compactFocusLayoutSchema.optional(),
+    laneSpacing: z.number().int().min(1).max(100).optional(),
+    nodeSpacing: z.number().int().min(1).max(100).optional(),
+})
+    .strict()
+    .superRefine((value, context) => {
+    const mode = value.mode ?? 'national';
+    if (mode === 'national' && value.paletteId !== undefined)
+        context.addIssue({
+            code: 'custom',
+            path: ['paletteId'],
+            message: 'paletteId is only valid in continuous mode',
+        });
+    if (mode === 'continuous' && value.treeId !== undefined)
+        context.addIssue({
+            code: 'custom',
+            path: ['treeId'],
+            message: 'treeId is only valid in national mode',
+        });
+    if (mode === 'continuous') {
+        for (const field of ['previous', 'laneSpacing', 'nodeSpacing']) {
+            if (value[field] !== undefined)
+                context.addIssue({
+                    code: 'custom',
+                    path: [field],
+                    message: `${field} is only valid in national mode`,
+                });
+        }
+    }
+    if (value.previous !== undefined && value.treeId === undefined)
+        context.addIssue({
+            code: 'custom',
+            path: ['previous'],
+            message: 'previous requires treeId so it applies to exactly one tree',
+        });
+});
+export const focusRenderRequestSchema = z
+    .object({
+    mode: z.enum(['national', 'continuous']).optional(),
+    workspaceId: workspaceIdSchema,
+    relativePath: workspaceRelativePathSchema,
+    treeId: z.string().min(1).max(256).optional(),
+    paletteId: z.string().min(1).max(256).optional(),
+    horizontalSpacing: z.number().int().min(80).max(1000).optional(),
+    verticalSpacing: z.number().int().min(60).max(1000).optional(),
+    reviewScale: z
+        .number()
+        .min(FOCUS_RENDER_MIN_OUTPUT_SCALE)
+        .max(FOCUS_RENDER_MAX_OUTPUT_SCALE)
+        .optional(),
+    columns: z.number().int().min(1).max(12).optional(),
+    padding: z.number().int().min(0).max(1000).optional(),
+})
+    .strict()
+    .superRefine((value, context) => {
+    const mode = value.mode ?? 'national';
+    const invalid = mode === 'national'
+        ? [
+            ['paletteId', value.paletteId],
+            ['columns', value.columns],
+        ]
+        : [
+            ['treeId', value.treeId],
+            ['horizontalSpacing', value.horizontalSpacing],
+            ['verticalSpacing', value.verticalSpacing],
+            ['reviewScale', value.reviewScale],
+        ];
+    for (const [field, fieldValue] of invalid) {
+        if (fieldValue !== undefined)
+            context.addIssue({
+                code: 'custom',
+                path: [field],
+                message: `${field} is not valid in ${mode} mode`,
+            });
+    }
+    if (mode === 'continuous' && value.padding !== undefined && value.padding < 24)
+        context.addIssue({
+            code: 'custom',
+            path: ['padding'],
+            message: 'continuous focus padding must be at least 24 pixels',
+        });
+});
+export const focusRewriteRequestSchema = z
+    .object({
+    mode: z.enum(['national', 'continuous']).optional(),
+    workspaceId: workspaceIdSchema,
+    relativePath: workspaceRelativePathSchema,
+    treeId: z.string().min(1).max(256).optional(),
+    layoutMode: z.enum(['authored', 'compact']).default('authored'),
+    plan: compactFocusPlanSchema.optional(),
+    createIfMissing: z.boolean().default(false),
+    horizontalSpacing: z.number().int().min(80).max(1000).optional(),
+    verticalSpacing: z.number().int().min(60).max(1000).optional(),
+    padding: z.number().int().min(0).max(1000).optional(),
+    reviewScale: z
+        .number()
+        .min(FOCUS_RENDER_MIN_OUTPUT_SCALE)
+        .max(FOCUS_RENDER_MAX_OUTPUT_SCALE)
+        .optional(),
+    requestKey: backgroundRequestKeySchema.optional(),
+})
+    .strict()
+    .superRefine((value, context) => {
+    const mode = value.mode ?? 'national';
+    const schema = mode === 'continuous' ? continuousFocusPaletteSchema : focusTreePlanSchema;
+    if (value.plan !== undefined && !schema.safeParse(value.plan).success)
+        context.addIssue({
+            code: 'custom',
+            path: ['plan'],
+            message: `plan must be a ${mode} focus plan`,
+        });
+    if (mode === 'continuous') {
+        if (value.plan === undefined)
+            context.addIssue({
+                code: 'custom',
+                path: ['plan'],
+                message: 'plan is required in continuous mode',
+            });
+        if (value.treeId !== undefined)
+            context.addIssue({
+                code: 'custom',
+                path: ['treeId'],
+                message: 'treeId is only valid in national mode',
+            });
+        if (value.layoutMode !== 'authored')
+            context.addIssue({
+                code: 'custom',
+                path: ['layoutMode'],
+                message: 'compact layout mode is only valid in national mode',
+            });
+        for (const [field, fieldValue] of [
+            ['horizontalSpacing', value.horizontalSpacing],
+            ['verticalSpacing', value.verticalSpacing],
+            ['padding', value.padding],
+            ['reviewScale', value.reviewScale],
+        ])
+            if (fieldValue !== undefined)
+                context.addIssue({
+                    code: 'custom',
+                    path: [field],
+                    message: `${field} is only valid for national focus review renders`,
+                });
+    }
+    else {
+        if (value.plan === undefined && value.layoutMode !== 'compact')
+            context.addIssue({
+                code: 'custom',
+                path: ['plan'],
+                message: 'plan is required unless layoutMode is compact',
+            });
+        if (value.plan === undefined && value.treeId === undefined)
+            context.addIssue({
+                code: 'custom',
+                path: ['treeId'],
+                message: 'treeId is required for plan-free compact reflow',
+            });
+        if (value.plan === undefined && value.createIfMissing)
+            context.addIssue({
+                code: 'custom',
+                path: ['createIfMissing'],
+                message: 'plan-free compact reflow requires an existing focus source',
+            });
+        if (value.plan !== undefined &&
+            value.treeId !== undefined &&
+            'id' in value.plan &&
+            value.plan.id !== value.treeId)
+            context.addIssue({
+                code: 'custom',
+                path: ['treeId'],
+                message: 'treeId must match the supplied national focus plan',
+            });
+    }
+});

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

@@ -0,0 +1,193 @@
+import { z } from 'zod/v4';
+import { renderDimensionViolation, RenderBudget, RENDER_MAX_DIMENSION, } from '../core/render-budget.js';
+import { ServiceError } from '../core/result.js';
+import { SOURCE_MAX_BYTES } from '../core/source/index.js';
+import { GUI_TEXT_PACKAGE_MAX_FILES, GuiHelperDocumentSchema } from '../gui/index.js';
+import { GuiGeneratedScenarioOptionsSchema, GuiPreviewScenarioSchema } from '../gui/scenario.js';
+import { backgroundRequestKeySchema, workspaceIdSchema, workspaceRelativePathSchema, } from './common.js';
+function compact(schema, description) {
+    return z.unknown().describe(description).pipe(schema);
+}
+const compactGuiScenarioSchema = compact(GuiPreviewScenarioSchema, 'GUI preview scenario.');
+const compactGeneratedScenarioOptionsSchema = compact(GuiGeneratedScenarioOptionsSchema, 'GUI generated-scenario options.');
+const compactGuiHelperSchema = compact(GuiHelperDocumentSchema, 'GUI helper document.');
+export const guiPreviewStateSchema = z.enum([
+    'normal',
+    'hover',
+    'selected',
+    'locked',
+    'disabled',
+    'warning',
+    'active',
+    'completed',
+    'empty-list',
+    'full-list',
+    'minimum-value',
+    'maximum-value',
+    'long-text',
+    'missing-localisation',
+]);
+export const guiInspectRequestSchema = z
+    .object({
+    workspaceId: workspaceIdSchema,
+    windowName: z.string().min(1).max(256).optional(),
+    scenario: compactGuiScenarioSchema.optional(),
+    relatedScenarios: z.array(compactGuiScenarioSchema).max(32).optional(),
+    generatedScenarios: compactGeneratedScenarioOptionsSchema.optional(),
+})
+    .strict()
+    .superRefine((value, context) => {
+    if ((value.windowName === undefined) !== (value.scenario === undefined))
+        context.addIssue({
+            code: 'custom',
+            message: 'windowName and scenario must be provided together',
+        });
+    if (value.relatedScenarios !== undefined && value.scenario === undefined)
+        context.addIssue({
+            code: 'custom',
+            path: ['relatedScenarios'],
+            message: 'relatedScenarios requires a window scenario',
+        });
+    if (value.generatedScenarios !== undefined && value.scenario === undefined)
+        context.addIssue({
+            code: 'custom',
+            path: ['generatedScenarios'],
+            message: 'generatedScenarios requires a window scenario',
+        });
+});
+export const guiResolutionSchema = z
+    .object({
+    width: z.number().int().min(320).max(RENDER_MAX_DIMENSION),
+    height: z.number().int().min(200).max(RENDER_MAX_DIMENSION),
+    uiScale: z
+        .number()
+        .min(0.25)
+        .max(4)
+        .optional()
+        .describe('In-game UI scale for this resolution. Use 1 at 1920x1080; do not use it to enlarge an artifact.'),
+})
+    .strict()
+    .superRefine(({ width, height }, context) => {
+    const violation = renderDimensionViolation(width, height, 'GUI matrix resolution');
+    if (violation !== undefined)
+        context.addIssue({ code: 'custom', message: `${violation.code}: ${violation.message}` });
+});
+export const guiRenderRequestSchema = z
+    .object({
+    workspaceId: workspaceIdSchema,
+    windowName: z.string().min(1).max(256),
+    scenario: compactGuiScenarioSchema,
+    states: z.array(guiPreviewStateSchema).max(14).optional(),
+    resolutions: z.array(guiResolutionSchema).min(1).max(16).optional(),
+    relatedScenarios: z.array(compactGuiScenarioSchema).max(32).optional(),
+    generatedScenarios: compactGeneratedScenarioOptionsSchema.optional(),
+    comparisonScenario: compactGuiScenarioSchema.optional(),
+})
+    .strict()
+    .superRefine(({ scenario, states, resolutions, relatedScenarios, generatedScenarios }, context) => {
+    const budget = new RenderBudget();
+    try {
+        const stateCount = states?.length ?? 14;
+        for (let index = 0; index < 9 + stateCount; index += 1)
+            budget.reserve(scenario.resolution.width, scenario.resolution.height, 'GUI request variant');
+        for (const resolution of resolutions ?? [
+            { width: 1280, height: 720 },
+            { width: 1920, height: 1080 },
+            { width: 2560, height: 1440 },
+            { width: 1920, height: 1080 },
+        ])
+            budget.reserve(resolution.width, resolution.height, 'GUI resolution variant');
+        const generatedCount = generatedScenarios?.enabled === false ? 0 : (generatedScenarios?.count ?? 1);
+        const scenarioCount = generatedCount === 0
+            ? 1 + (relatedScenarios?.length ?? 0)
+            : generatedCount +
+                (generatedScenarios?.preservePlaceholder === false ? 0 : 1) +
+                (relatedScenarios?.length ?? 0);
+        const stateColumns = Math.min(3, Math.max(1, stateCount));
+        const stateRows = Math.max(1, Math.ceil(stateCount / stateColumns));
+        budget.reserve(stateColumns * 420, 46 + stateRows * 280, 'GUI state gallery');
+        const resolutionCount = resolutions?.length ?? 4;
+        const resolutionColumns = Math.min(3, Math.max(1, resolutionCount));
+        const resolutionRows = Math.max(1, Math.ceil(resolutionCount / resolutionColumns));
+        budget.reserve(resolutionColumns * 420, 46 + resolutionRows * 280, 'GUI resolution gallery');
+        const scenarioBudget = new RenderBudget();
+        const scenarioColumns = Math.min(3, Math.max(1, scenarioCount));
+        const scenarioRows = Math.max(1, Math.ceil(scenarioCount / scenarioColumns));
+        scenarioBudget.reserve(scenarioColumns * 420, 46 + scenarioRows * 280, 'GUI scripted scenario gallery');
+    }
+    catch (error) {
+        if (error instanceof ServiceError) {
+            context.addIssue({ code: 'custom', message: `${error.code}: ${error.message}` });
+            return;
+        }
+        throw error;
+    }
+});
+export const guiRewriteRequestSchema = z
+    .object({
+    mode: z.enum(['source', 'helpers', 'patches']),
+    workspaceId: workspaceIdSchema,
+    relativePath: workspaceRelativePathSchema,
+    windowName: z.string().min(1).max(256),
+    scenario: compactGuiScenarioSchema,
+    requestKey: backgroundRequestKeySchema.optional(),
+    source: z.string().max(SOURCE_MAX_BYTES).optional(),
+    helper: compactGuiHelperSchema.optional(),
+    additionalFiles: z
+        .array(z
+        .object({
+        relativePath: workspaceRelativePathSchema,
+        source: z.string().max(SOURCE_MAX_BYTES),
+    })
+        .strict())
+        .max(GUI_TEXT_PACKAGE_MAX_FILES - 1)
+        .optional(),
+    expectedSourceHash: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .optional(),
+    patches: z
+        .array(z
+        .object({
+        start: z.number().int().min(0),
+        end: z.number().int().min(0),
+        expectedText: z.string().max(5_000_000),
+        text: z.string().max(5_000_000),
+        description: z.string().min(1).max(1000),
+    })
+        .strict())
+        .min(1)
+        .max(1000)
+        .optional(),
+})
+    .strict()
+    .superRefine((value, context) => {
+    if (value.mode === 'source' && value.source === undefined)
+        context.addIssue({ code: 'custom', message: 'source is required in source mode' });
+    if (value.mode === 'helpers' && value.helper === undefined)
+        context.addIssue({ code: 'custom', message: 'helper is required in helpers mode' });
+    if (value.mode === 'patches' &&
+        (value.patches === undefined || value.expectedSourceHash === undefined))
+        context.addIssue({
+            code: 'custom',
+            message: 'patches and expectedSourceHash are required in patches mode',
+        });
+    if (value.mode === 'source' && value.helper !== undefined)
+        context.addIssue({ code: 'custom', message: 'helper is forbidden in source mode' });
+    if (value.mode === 'helpers' && value.source !== undefined)
+        context.addIssue({ code: 'custom', message: 'source is forbidden in helpers mode' });
+    if (value.mode !== 'patches' &&
+        (value.patches !== undefined || value.expectedSourceHash !== undefined))
+        context.addIssue({
+            code: 'custom',
+            message: 'patch fields are accepted only in patches mode',
+        });
+    if (value.mode === 'patches' &&
+        (value.source !== undefined ||
+            value.helper !== undefined ||
+            value.additionalFiles !== undefined))
+        context.addIssue({
+            code: 'custom',
+            message: 'source, helper, and additionalFiles are forbidden in patches mode',
+        });
+});

package/dist/hoi4_agent_tools/schemas/helper-expansion.js

@@ -0,0 +1,58 @@
+import { z } from 'zod/v4';
+export const helperExpansionRequestSchema = z
+    .object({
+    rootIds: z.array(z.string().min(1).max(1_024)).min(1).max(2_000).optional(),
+    maxDepth: z.number().int().min(1).max(256).optional(),
+    maxRecords: z.number().int().min(1).max(5_000).optional(),
+    maxWork: z.number().int().min(1).max(100_000).optional(),
+    continuationUri: z
+        .string()
+        .min(1)
+        .max(8_192)
+        .regex(/^hoi4-agent:\/\//u)
+        .optional(),
+})
+    .strict();
+const count = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+export const helperExpansionSummarySchema = z
+    .object({
+    complete: z.boolean(),
+    finished: z.boolean(),
+    sourceComplete: z.boolean(),
+    maxDepth: count,
+    records: count,
+    totalRecords: count,
+    work: count,
+    totalWork: count,
+    completedRoots: count,
+    totalRoots: count,
+    cycles: count,
+    depthStops: count,
+    continuationUri: z
+        .string()
+        .max(8_192)
+        .regex(/^hoi4-agent:\/\//u)
+        .optional(),
+})
+    .strict();
+/** A dedicated mode must not silently ignore filters belonging to other inspection modes. */
+export function validateHelperExpansionMode(value, context) {
+    const fields = value;
+    if (fields.mode !== 'helper_expansion') {
+        if (fields.helperExpansion !== undefined)
+            context.addIssue({
+                code: 'custom',
+                path: ['helperExpansion'],
+                message: 'helperExpansion requires helper_expansion mode',
+            });
+        return;
+    }
+    const allowed = new Set(['workspaceId', 'mode', 'helperExpansion', 'refresh']);
+    for (const [field, content] of Object.entries(fields))
+        if (content !== undefined && !allowed.has(field))
+            context.addIssue({
+                code: 'custom',
+                path: [field],
+                message: 'Use helperExpansion rootIds and bounds in helper_expansion mode',
+            });
+}

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

@@ -0,0 +1,85 @@
+import { z } from 'zod/v4';
+import { MAP_PROVINCE_GEOMETRY_SELECTOR_LIMIT } from '../map/limits.js';
+import { backgroundRequestKeySchema, workspaceIdSchema } from './common.js';
+import { mapAllocationRequestSchema, mapOperationSchema } from './map.js';
+function compact(schema, description) {
+    return z.unknown().describe(description).pipe(schema);
+}
+const compactMapOperationSchema = compact(mapOperationSchema, 'Complete map operation.');
+export const mapLayerSchema = z.enum([
+    'province',
+    'state',
+    'strategic-region',
+    'terrain',
+    'continent',
+    'owner',
+    'controller',
+    'cores',
+    'claims',
+    'coast',
+]);
+export const mapOverlaySchema = z.enum([
+    'coastlines',
+    'ports',
+    'victory-points',
+    'resources',
+    'state-buildings',
+    'province-buildings',
+    'supply-nodes',
+    'railways',
+    'adjacencies',
+    'building-positions',
+    'unit-positions',
+    'weather-positions',
+]);
+export const mapInspectRequestSchema = z
+    .object({
+    workspaceId: workspaceIdSchema,
+    provinceIds: z
+        .array(z.number().int().min(0))
+        .max(MAP_PROVINCE_GEOMETRY_SELECTOR_LIMIT)
+        .default([])
+        .describe(`Export row runs for up to ${MAP_PROVINCE_GEOMETRY_SELECTOR_LIMIT} province IDs`),
+    stateIds: z.array(z.number().int().positive()).max(1_000).default([]),
+    regionIds: z.array(z.number().int().positive()).max(1_000).default([]),
+    query: z.string().max(256).optional(),
+    queryLimit: z.number().int().min(1).max(1_000).default(100),
+    coordinates: z
+        .array(z.discriminatedUnion('kind', [
+        z
+            .object({
+            kind: z.literal('pixel'),
+            x: z.number().int().min(0),
+            y: z.number().int().min(0),
+        })
+            .strict(),
+        z
+            .object({
+            kind: z.literal('map'),
+            x: z.number(),
+            z: z.number(),
+        })
+            .strict(),
+    ]))
+        .max(100)
+        .default([]),
+    includeOverview: z.boolean().default(true),
+    allocationRequests: z.array(mapAllocationRequestSchema).max(100).default([]),
+})
+    .strict();
+export const mapRenderRequestSchema = z
+    .object({
+    workspaceId: workspaceIdSchema,
+    layer: mapLayerSchema.optional(),
+    overlays: z.array(mapOverlaySchema).max(12).optional(),
+    scale: z.number().int().min(1).max(16).optional(),
+})
+    .strict();
+export const mapRewriteRequestSchema = z
+    .object({
+    workspaceId: workspaceIdSchema,
+    operations: z.array(compactMapOperationSchema).min(1).max(100),
+    diffScale: z.number().int().min(1).max(16).optional(),
+    requestKey: backgroundRequestKeySchema.optional(),
+})
+    .strict();