hoi4-agent-tools 3.10.0 → 4.0.1

package/dist/hoi4_agent_tools/schemas/lenient-arguments.js

@@ -0,0 +1,266 @@
+/**
+ * Accept the argument shorthands coding agents most often send and rewrite them into the
+ * canonical request before validation. Every rule maps one unambiguous shorthand to exactly one
+ * canonical value; anything ambiguous is left alone so validation can name the field.
+ *
+ * The rules come from failed calls observed in agent transcripts: an event selector given as a
+ * plain string or without its kind, a GUI scenario without an id, a decision inspection without
+ * a scenario, a probability scenario set without ids or state, a scenario set sent as a bare
+ * array, a namespace wildcard such as `chaosx.nr14.*`, a trace given `from` instead of `selector`,
+ * and a script file check that also names the kind and scope its file already fixes.
+ */
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+const EVENT_ID = /^[A-Za-z0-9_.-]+\.[0-9]+$/u;
+/** A size limit above the accepted maximum means "as many as allowed", not an invalid call. */
+function clampLimits(args, maximums) {
+    for (const [key, maximum] of Object.entries(maximums)) {
+        const value = args[key];
+        if (typeof value === 'number' && Number.isFinite(value) && value > maximum)
+            args[key] = maximum;
+    }
+}
+/** A selector object that names its kind but uses `id` or `path` for the kind's own field. */
+function withKindField(value) {
+    const { kind, id, path, ...rest } = value;
+    const field = {
+        event: 'eventId',
+        namespace: 'namespace',
+        file: 'sourcePath',
+        source: 'sourcePath',
+        node: 'nodeId',
+    };
+    const target = typeof kind === 'string' ? field[kind] : undefined;
+    if (target === undefined || rest[target] !== undefined)
+        return value;
+    const given = target === 'sourcePath' ? (path ?? id) : (id ?? path);
+    if (typeof given !== 'string')
+        return value;
+    const extra = target === 'sourcePath' ? (path === undefined ? {} : { id }) : { path };
+    return Object.fromEntries(Object.entries({
+        kind,
+        [target]: kind === 'namespace' ? withoutWildcard(given) : given,
+        ...rest,
+        ...extra,
+    }).filter(([, entry]) => entry !== undefined));
+}
+/** `chaosx.nr14.*`, `chaosx.nr14.` and `chaosx.nr14*` all name the namespace `chaosx.nr14`. */
+function withoutWildcard(value) {
+    return value.replace(/\.?\*+$|\.$/u, '');
+}
+/** An event selector as a string or an object without `kind`. */
+export function normalizeEventSelector(value) {
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (EVENT_ID.test(trimmed))
+            return { kind: 'event', eventId: trimmed };
+        if (/\.txt$/iu.test(trimmed) || trimmed.includes('/'))
+            return { kind: 'file', sourcePath: trimmed };
+        return { kind: 'namespace', namespace: withoutWildcard(trimmed) };
+    }
+    if (isObject(value) && value.kind !== undefined)
+        return withKindField(value);
+    if (!isObject(value))
+        return value;
+    const keys = Object.keys(value);
+    const only = (...allowed) => keys.every((key) => allowed.includes(key));
+    if (typeof value.eventId === 'string' && only('eventId'))
+        return { kind: 'event', eventId: value.eventId };
+    if (typeof value.id === 'string' && only('id'))
+        return EVENT_ID.test(value.id)
+            ? { kind: 'event', eventId: value.id }
+            : { kind: 'namespace', namespace: withoutWildcard(value.id) };
+    if (typeof value.namespace === 'string' && only('namespace'))
+        return { kind: 'namespace', namespace: withoutWildcard(value.namespace) };
+    const sourcePath = typeof value.sourcePath === 'string'
+        ? value.sourcePath
+        : typeof value.path === 'string'
+            ? value.path
+            : undefined;
+    if (sourcePath !== undefined && only('sourcePath', 'path', 'line', 'column')) {
+        if (typeof value.line === 'number')
+            return {
+                kind: 'source',
+                sourcePath,
+                line: value.line,
+                ...(typeof value.column === 'number' ? { column: value.column } : {}),
+            };
+        return { kind: 'file', sourcePath };
+    }
+    if (typeof value.nodeId === 'string' && only('nodeId'))
+        return { kind: 'node', nodeId: value.nodeId };
+    return value;
+}
+/** A scenario object without `id` takes its `name` or `label`, or a positional id. */
+function withScenarioId(scenario, fallback) {
+    if (!isObject(scenario) || scenario.id !== undefined)
+        return scenario;
+    const { name, ...rest } = scenario;
+    const id = typeof name === 'string' && name.length > 0
+        ? name
+        : typeof scenario.label === 'string' && scenario.label.length > 0
+            ? scenario.label
+            : fallback;
+    return { id, ...rest };
+}
+function normalizeGuiScenario(value, fallback) {
+    return withScenarioId(value, fallback);
+}
+function normalizeConditionScenario(value, index) {
+    const scenario = withScenarioId(value, `scenario-${index + 1}`);
+    if (!isObject(scenario))
+        return scenario;
+    return scenario.state === undefined ? { ...scenario, state: {} } : scenario;
+}
+/** A probability scenario set as a bare array, or without its id. */
+function normalizeScenarioSet(value) {
+    const set = Array.isArray(value) ? { scenarios: value } : value;
+    if (!isObject(set) || !Array.isArray(set.scenarios))
+        return set;
+    return {
+        ...set,
+        ...(set.id === undefined ? { id: 'scenarios' } : {}),
+        scenarios: set.scenarios.map((scenario, index) => normalizeConditionScenario(scenario, index)),
+    };
+}
+function normalizeEventArguments(args) {
+    const result = { ...args };
+    // A top-level event ID, namespace or file stands for the selector.
+    if (result.selector === undefined)
+        for (const key of ['eventId', 'id', 'namespace', 'event'])
+            if (typeof result[key] === 'string') {
+                result.selector = result[key];
+                Reflect.deleteProperty(result, key);
+                break;
+            }
+    // Modes that start from one event take `selector`; `from` alone means the same event.
+    if (result.selector === undefined &&
+        result.to === undefined &&
+        result.from !== undefined &&
+        result.mode !== 'explain_path') {
+        result.selector = result.from;
+        delete result.from;
+    }
+    for (const key of ['selector', 'from', 'to'])
+        if (result[key] !== undefined)
+            result[key] = normalizeEventSelector(result[key]);
+    return result;
+}
+/**
+ * A file check reads each block's kind and scope from the file, so a kind or scope sent with
+ * `path` is redundant and dropped. `file` names the path and `snippet`, `code` or `text` the
+ * source; a snippet without a scope runs in country scope.
+ */
+function normalizeScriptValidateArguments(args) {
+    const result = { ...args };
+    clampLimits(result, { limit: 32 });
+    for (const alias of ['file', 'filePath', 'sourcePath'])
+        if (result.path === undefined && typeof result[alias] === 'string') {
+            result.path = result[alias];
+            Reflect.deleteProperty(result, alias);
+        }
+    for (const alias of ['snippet', 'code', 'text', 'script', 'body'])
+        if (result.source === undefined && typeof result[alias] === 'string') {
+            result.source = result[alias];
+            Reflect.deleteProperty(result, alias);
+        }
+    if (typeof result.path === 'string' && result.source === undefined) {
+        delete result.kind;
+        delete result.scope;
+        if (Array.isArray(result.bindings) && result.bindings.length === 0)
+            delete result.bindings;
+    }
+    if (typeof result.source === 'string' && result.path === undefined && result.scope === undefined)
+        result.scope = 'country';
+    return result;
+}
+function normalizeGuiArguments(args, defaultScenario) {
+    const result = { ...args };
+    const fallback = typeof result.windowName === 'string' ? result.windowName : 'default';
+    if (result.scenario !== undefined)
+        result.scenario = normalizeGuiScenario(result.scenario, fallback);
+    // A window inspection without a scenario reads the window in its default state.
+    else if (defaultScenario || typeof result.windowName === 'string')
+        result.scenario = { id: fallback };
+    if (Array.isArray(result.relatedScenarios))
+        result.relatedScenarios = result.relatedScenarios.map((scenario, index) => normalizeGuiScenario(scenario, `${fallback}-${index + 1}`));
+    if (isObject(result.generatedScenarios)) {
+        const { maxScenarios, ...rest } = result.generatedScenarios;
+        result.generatedScenarios =
+            typeof maxScenarios === 'number' && rest.count === undefined
+                ? { ...rest, count: maxScenarios }
+                : result.generatedScenarios;
+    }
+    return result;
+}
+function normalizeDecisionArguments(args) {
+    const result = { ...args };
+    for (const alias of ['decisionId', 'decision', 'missionId'])
+        if (result.id === undefined && typeof result[alias] === 'string') {
+            result.id = result[alias];
+            Reflect.deleteProperty(result, alias);
+        }
+    if (result.mode === undefined && typeof result.id === 'string')
+        result.mode = 'inspect';
+    if (Array.isArray(result.scenarios))
+        result.scenarios = result.scenarios.map((scenario, index) => normalizeConditionScenario(scenario, index));
+    const mode = result.mode ?? 'inventory';
+    if ((mode === 'inspect' || mode === 'compare') &&
+        (result.scenarios === undefined ||
+            (Array.isArray(result.scenarios) && result.scenarios.length === 0))) {
+        result.scenarios = [
+            {
+                id: 'no-facts',
+                state: {},
+                ...(typeof result.actor === 'string' ? { actor: result.actor } : {}),
+            },
+        ];
+        if (typeof result.actor === 'string')
+            delete result.actor;
+    }
+    return result;
+}
+function normalizeProbabilityArguments(args) {
+    const result = { ...args };
+    if (result.scenarioSet !== undefined)
+        result.scenarioSet = normalizeScenarioSet(result.scenarioSet);
+    if (typeof result.source === 'string')
+        result.source = /\.txt$/iu.test(result.source)
+            ? { path: result.source }
+            : { identifier: result.source };
+    if (typeof result.candidatePool === 'string')
+        result.candidatePool = [result.candidatePool];
+    return result;
+}
+/** Rewrite known shorthands for one tool; unknown tools and non-object arguments pass through. */
+export function normalizeToolArguments(name, args) {
+    if (!isObject(args))
+        return args;
+    switch (name) {
+        case 'hoi4.event_inspect': {
+            const result = normalizeEventArguments(args);
+            clampLimits(result, { maxDepth: 64, maxNodes: 5_000, maxEdges: 20_000 });
+            return result;
+        }
+        case 'hoi4.event_render': {
+            const result = normalizeEventArguments(args);
+            clampLimits(result, { maxDepth: 64, maxNodes: 240 });
+            return result;
+        }
+        case 'hoi4.gui_inspect':
+            return normalizeGuiArguments(args, false);
+        case 'hoi4.gui_render':
+        case 'hoi4.gui_rewrite':
+            return normalizeGuiArguments(args, true);
+        case 'hoi4.decision_inspect':
+            return normalizeDecisionArguments(args);
+        case 'hoi4.script_validate':
+            return normalizeScriptValidateArguments(args);
+        case 'hoi4.probability_inspect':
+        case 'hoi4.probability_analyze':
+            return normalizeProbabilityArguments(args);
+        default:
+            return args;
+    }
+}

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

@@ -32,6 +32,33 @@ export const mapOverlaySchema = z.enum([
     'unit-positions',
     'weather-positions',
 ]);
+const mapTileSchema = 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();
+const mapAreaSchema = 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');
+/** Fields that select a rendered map view instead of validation and lookups. */
+export const MAP_VIEW_FIELDS = ['layer', 'overlays', 'scale', 'tile', 'area'];
+const MAP_LOOKUP_FIELDS = [
+    'provinceIds',
+    'stateIds',
+    'regionIds',
+    'query',
+    'coordinates',
+    'allocationRequests',
+];
 export const mapInspectRequestSchema = z
     .object({
     workspaceId: workspaceIdSchema,
@@ -66,33 +93,49 @@ export const mapInspectRequestSchema = z
     lookupOnly: z.boolean().default(false),
     includeOverview: z.boolean().default(true),
     allocationRequests: z.array(mapAllocationRequestSchema).max(100).default([]),
+    references: z
+        .boolean()
+        .default(false)
+        .describe('Also check events, focuses, decisions, history and AI areas for states, provinces and regions the map lacks, and state tags without a country.'),
+    layer: mapLayerSchema
+        .optional()
+        .describe('Render this base layer; combine with overlays, tile or area.'),
+    overlays: z.array(mapOverlaySchema).max(12).optional(),
+    scale: z.number().int().min(1).max(16).optional(),
+    tile: mapTileSchema.optional().describe('Render one top-left bitmap area.'),
+    area: mapAreaSchema
+        .optional()
+        .describe('Render the bounding area of these provinces, states or regions.'),
 })
-    .strict();
+    .strict()
+    .superRefine((value, context) => {
+    if (value.tile !== undefined && value.area !== undefined)
+        context.addIssue({
+            code: 'custom',
+            path: ['area'],
+            message: 'Choose tile or area, not both',
+        });
+    if (!MAP_VIEW_FIELDS.some((field) => value[field] !== undefined))
+        return;
+    for (const field of MAP_LOOKUP_FIELDS) {
+        const fieldValue = value[field];
+        if (fieldValue !== undefined && !(Array.isArray(fieldValue) && fieldValue.length === 0))
+            context.addIssue({
+                code: 'custom',
+                path: [field],
+                message: `${field} is a lookup; request a rendered view (layer, overlays, tile, area, scale) in a separate call`,
+            });
+    }
+});
+/** Internal render request derived from a map inspection that names a view. */
 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(),
-    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(),
+    tile: mapTileSchema.optional(),
+    area: mapAreaSchema.optional(),
 })
     .strict()
     .refine(({ tile, area }) => tile === undefined || area === undefined, 'Choose tile or area, not both');

package/dist/hoi4_agent_tools/schemas/map.js

@@ -20,7 +20,7 @@ const operationBase = {
 };
 const moveStateDistributionSchema = z
     .object({
-    stateValues: z.literal('retain-in-current-states'),
+    stateValues: z.enum(['retain-in-current-states', 'proportional-by-land-pixels']),
     ownership: z.literal('retain-in-current-states'),
     provinceBuildings: z.literal('follow-province'),
     victoryPoints: z.literal('follow-province'),
@@ -276,6 +276,7 @@ const splitStateOperation = (kind) => z
     fileName: z.string().max(255).optional(),
     localisation: stateLocalisationSchema.optional(),
     distribution: splitStateDistributionSchema,
+    remapReferences: z.enum(['refuse', 'override']).optional(),
 })
     .strict();
 const createStateOperation = z
@@ -290,6 +291,7 @@ const createStateOperation = z
     fileName: z.string().max(255).optional(),
     localisation: stateLocalisationSchema.optional(),
     distribution: z.union([z.literal('proportional'), splitStateDistributionSchema]).optional(),
+    remapReferences: z.enum(['refuse', 'override']).optional(),
 })
     .strict()
     .refine((value) => value.name !== undefined || value.displayName !== undefined, {
@@ -329,7 +331,7 @@ export const mapOperationSchema = z.discriminatedUnion('kind', [
         sourceStateId: stateId,
         targetStateId: stateId,
         provinceIds: z.array(provinceId).min(1).max(100_000),
-        distribution: moveStateDistributionSchema,
+        distribution: z.union([z.literal('proportional'), moveStateDistributionSchema]).optional(),
     })
         .strict(),
     z
@@ -408,7 +410,22 @@ export const mapOperationSchema = z.discriminatedUnion('kind', [
         kind: z.literal('merge_states'),
         sourceStateIds: z.array(stateId).min(1).max(100_000),
         targetStateId: stateId,
-        distribution: mergeStateDistributionSchema,
+        // Every merge policy has one allowed value, so the whole object may be omitted.
+        distribution: mergeStateDistributionSchema.default({
+            stateValues: 'sum-into-target',
+            ownership: 'retain-target',
+            controller: 'retain-target',
+            cores: 'union',
+            claims: 'union',
+            victoryPoints: 'follow-province',
+            provinceBuildings: 'follow-province',
+            ports: 'follow-province',
+            supplyNodes: 'follow-province',
+            railways: 'follow-province',
+            positions: 'follow-province',
+            strategicRegion: 'require-same',
+        }),
+        remapReferences: z.enum(['refuse', 'override']).optional(),
     })
         .strict(),
     splitProvinceOperation('split_province'),
@@ -452,6 +469,108 @@ export const mapOperationSchema = z.discriminatedUnion('kind', [
         distribution: z.literal('move-membership'),
     })
         .strict(),
+    z
+        .object({
+        ...operationBase,
+        kind: z.literal('create_world'),
+        width: z.number().int().min(256).max(8_192).multipleOf(256).default(1_024),
+        height: z.number().int().min(256).max(4_096).multipleOf(256).default(512),
+        seed: z.number().int().min(0).max(2_147_483_647).default(1),
+        landCoverage: z.number().min(0.05).max(0.9).default(0.35),
+        continents: z.number().int().min(1).max(12).default(3),
+        landPolygons: z
+            .array(z.array(pointSchema).min(3).max(10_000))
+            .max(64)
+            .optional()
+            .describe('Land outlines in top-left pixel coordinates; omit for generated continents.'),
+        landProvincePixels: z.number().int().min(60).max(50_000).default(400),
+        seaProvincePixels: z.number().int().min(200).max(200_000).default(2_500),
+        provincesPerState: z.number().int().min(1).max(64).default(5),
+        landProvincesPerRegion: z.number().int().min(2).max(400).default(25),
+        seaProvincesPerRegion: z.number().int().min(1).max(200).default(10),
+        countries: z
+            .array(z
+            .object({
+            tag: z.string().regex(/^[A-Z][A-Z0-9]{2}$/u),
+            name: z.string().min(1).max(64),
+            adjective: z.string().min(1).max(64).optional(),
+            color: rgbSchema.optional(),
+            share: z.number().min(0.05).max(100).optional(),
+            ideology: z.enum(['democratic', 'communism', 'fascism', 'neutrality']).optional(),
+        })
+            .strict())
+            .min(1)
+            .max(200),
+        continentNames: z.array(z.string().min(1).max(64)).max(12).optional(),
+        startDate: z
+            .string()
+            .regex(/^\d{3,4}\.\d{1,2}\.\d{1,2}$/u)
+            .default('1936.1.1'),
+        rivers: z.number().int().min(0).max(500).default(8),
+        replaceBaseGame: z
+            .boolean()
+            .default(true)
+            .describe('Add replace_path for the base game states, countries, units, strategic regions, supply areas and bookmarks to descriptor.mod.'),
+    })
+        .strict(),
+    z
+        .object({
+        ...operationBase,
+        kind: z.literal('remap_map_references'),
+        entity: z.enum(['province', 'state', 'strategic-region']),
+        mapping: z
+            .array(z
+            .object({
+            from: z.number().int().min(0),
+            to: z
+                .union([
+                z.number().int().min(0),
+                z.array(z.number().int().min(0)).min(1).max(16),
+                z.null(),
+            ])
+                .describe('One ID replaces; several IDs copy the referencing assignment once per ID; null removes it.'),
+        })
+            .strict())
+            .min(1)
+            .max(1_000),
+        readOnlySources: z
+            .enum(['refuse', 'override'])
+            .default('refuse')
+            .describe('override copies game or dependency files that need the change into the mod.'),
+        pathPrefixes: z.array(z.string().min(1).max(256)).max(32).optional(),
+    })
+        .strict(),
+    z
+        .object({
+        ...operationBase,
+        kind: z.literal('regenerate_map_positions'),
+        positions: z
+            .array(z.enum(['buildings', 'units', 'weather']))
+            .min(1)
+            .max(3)
+            .default(['buildings', 'units', 'weather']),
+        stateIds: z.array(stateId).max(10_000).optional(),
+        provinceIds: z.array(provinceId).max(100_000).optional(),
+        regionIds: z.array(z.number().int().positive()).max(10_000).optional(),
+        mode: z
+            .enum(['missing', 'replace'])
+            .default('missing')
+            .describe('missing adds only absent positions; replace rewrites them for the selection.'),
+    })
+        .strict(),
+    z
+        .object({
+        ...operationBase,
+        kind: z.literal('rebuild_supply'),
+        stateIds: z.array(stateId).max(10_000).optional(),
+        mode: z
+            .enum(['connect', 'replace'])
+            .default('connect')
+            .describe('connect adds a supply node to each selected state without one and links unconnected nodes by railway; replace rebuilds the whole network.'),
+        railwayLevel: z.number().int().min(1).max(5).default(1),
+        capitalRailwayLevel: z.number().int().min(1).max(5).default(3),
+    })
+        .strict(),
     z
         .object({
         ...operationBase,