hoi4-agent-tools 3.9.0 → 4.0.0

package/dist/hoi4_agent_tools/reference/operations.js

@@ -8,6 +8,9 @@ import { ReferenceService } from './service.js';
 import { sourceLookup } from './source-lookup.js';
 import { scriptValidateDataSchema, scriptValidateRequestSchema, } from '../schemas/script-validation.js';
 import { validateScript } from './script-validation.js';
+import { readErrorLog } from './error-log.js';
+import { modIndex } from './mod-index.js';
+import { errorLogDataSchema, errorLogRequestSchema, modIndexDataSchema, modIndexRequestSchema, } from '../schemas/mod-tools.js';
 import { eventPopupDefinitions } from './event-popups.js';
 import { locatePatterns, selectFile } from './source-locate.js';
 /**
@@ -43,6 +46,8 @@ const schemas = {
     'hoi4.reference_context': referenceContextRequestSchema,
     'hoi4.source_lookup': sourceLookupRequestSchema,
     'hoi4.script_validate': scriptValidateRequestSchema,
+    'hoi4.error_log': errorLogRequestSchema,
+    'hoi4.mod_index': modIndexRequestSchema,
 };
 export function isReferenceTool(name) {
     return Object.hasOwn(schemas, name);
@@ -69,10 +74,34 @@ export class ReferenceToolService {
                 ? await this.references.read(workspace, referenceReadRequestSchema.parse(parsed), signal)
                 : name === 'hoi4.reference_context'
                     ? await this.references.context(workspace, referenceContextRequestSchema.parse(parsed), signal)
-                    : name === 'hoi4.script_validate'
-                        ? await this.validateScript(workspaceId, workspace, scriptValidateRequestSchema.parse(parsed), context.principal, signal)
-                        : await sourceLookup(this.engine, workspaceId, sourceLookupRequestSchema.parse(parsed), context.principal, signal);
+                    : name === 'hoi4.error_log'
+                        ? await readErrorLog(workspace, errorLogRequestSchema.parse(parsed), this.engine.resolver.config().gameUserRoot, signal)
+                        : name === 'hoi4.mod_index'
+                            ? await modIndex(this.engine, workspaceId, modIndexRequestSchema.parse(parsed), context.principal, signal)
+                            : name === 'hoi4.script_validate'
+                                ? await this.validateScript(workspaceId, workspace, scriptValidateRequestSchema.parse(parsed), context.principal, signal)
+                                : await sourceLookup(this.engine, workspaceId, sourceLookupRequestSchema.parse(parsed), context.principal, signal);
         const result = emptyServiceResult(workspaceId, data);
+        if (name === 'hoi4.error_log') {
+            const log = errorLogDataSchema.parse(data);
+            result.code = 'ERROR_LOG_READ';
+            result.validation = {
+                passed: log.modEntries === 0,
+                checks: [
+                    {
+                        id: 'error-log-mod-entries',
+                        passed: log.modEntries === 0,
+                        message: log.modEntries === 0
+                            ? 'The last game launch logged no errors located in this mod'
+                            : `The last game launch logged ${log.modEntries} distinct errors located in this mod`,
+                    },
+                ],
+            };
+        }
+        if (name === 'hoi4.mod_index') {
+            const index = modIndexDataSchema.parse(data);
+            result.code = index.complete ? 'MOD_INDEXED' : 'MOD_INDEXED_PARTIAL';
+        }
         if (name === 'hoi4.script_validate') {
             const checked = scriptValidateDataSchema.parse(data);
             result.code = checked.valid === null ? 'SCRIPT_CHECK_PARTIAL' : 'SCRIPT_CHECKED';
@@ -117,20 +146,32 @@ export class ReferenceToolService {
     #playerText = new Map();
     /** File mode reads the scanned file and the mod's scripted helper names from one scan. */
     async validateScript(workspaceId, workspace, request, principal, signal) {
-        if (request.path === undefined)
-            return validateScript(this.references, workspace, request, signal);
-        const snapshot = await this.engine.scan(workspaceId, {
-            patterns: [
-                ...(locatePatterns(this.engine, workspaceId, request.path, principal) ?? []),
-                'common/scripted_effects/**/*.txt',
-                'common/scripted_triggers/**/*.txt',
-                ...Object.keys(implicitTriggerSources).map((folder) => `common/${folder}/*.txt`),
-                // One scan serves every check: the engine keeps one snapshot per workspace.
-                ...playerTextPatterns,
-                'events/**/*.txt',
-            ],
-        }, principal, signal);
-        const file = selectFile(snapshot, request.path);
+        if (request.path === undefined) {
+            if (request.kind !== undefined)
+                return validateScript(this.references, workspace, request, signal);
+            // A snippet without a kind is checked as an effect and as a trigger; the reading with
+            // fewer errors and unresolved commands is the one the author meant.
+            const effect = await validateScript(this.references, workspace, { ...request, kind: 'effect' }, signal);
+            const trigger = await validateScript(this.references, workspace, { ...request, kind: 'trigger' }, signal);
+            const misses = (checked) => checked.findings.filter(({ status }) => status === 'error').length * 100_000 +
+                checked.unresolvedCount;
+            return misses(trigger) < misses(effect) ? trigger : effect;
+        }
+        // Every file check of the supported families shares one scan, so checking files across
+        // folders reuses one snapshot and its incremental index; other folders add their own.
+        const scan = (extra) => this.engine.scan(workspaceId, { patterns: [...fileCheckPatterns, ...extra] }, principal, signal);
+        let snapshot = await scan([]);
+        let file;
+        try {
+            file = selectFile(snapshot, request.path);
+        }
+        catch (error) {
+            const extra = locatePatterns(this.engine, workspaceId, request.path, principal);
+            if (extra === undefined)
+                throw error;
+            snapshot = await scan(extra);
+            file = selectFile(snapshot, request.path);
+        }
         const playerText = playerTextFamily(file.relativePath)
             ? this.playerTextContext(workspaceId, snapshot)
             : undefined;
@@ -143,8 +184,26 @@ export class ReferenceToolService {
             implicitTriggers: implicitTriggerNames(snapshot),
             ...(playerText === undefined ? {} : { playerText }),
             eventPopups: this.eventPopupContext(workspaceId, snapshot),
+            knownMistakes: { eventNamespaces: this.eventNamespaces(workspaceId, snapshot) },
         });
     }
+    #eventNamespaces = new Map();
+    /** Namespaces declared with `add_namespace` in every active events file, cached by hash. */
+    eventNamespaces(workspaceId, snapshot) {
+        const sources = [...snapshot.index.files.values()].filter(({ relativePath, shadowedBy }) => shadowedBy === undefined && relativePath.startsWith('events/'));
+        const cacheKey = hashCanonical(sources.map(({ displayPath, sha256 }) => [displayPath, sha256]));
+        const cached = this.#eventNamespaces.get(workspaceId);
+        if (cached?.key === cacheKey)
+            return cached.namespaces;
+        const namespaces = new Set();
+        for (const file of sources)
+            for (const match of file.bytes
+                .toString('utf8')
+                .matchAll(/^\s*add_namespace\s*=\s*"?([\w.]+)"?/gmu))
+                namespaces.add(match[1]);
+        this.#eventNamespaces.set(workspaceId, { key: cacheKey, namespaces });
+        return namespaces;
+    }
     /** Every active event definition, cached by the hashes of the events files. */
     eventPopupContext(workspaceId, snapshot) {
         const sources = [...snapshot.index.files.values()]
@@ -170,7 +229,9 @@ export class ReferenceToolService {
             return cached.context;
         const localisation = new Map();
         for (const symbol of snapshot.index.symbols) {
-            if (symbol.kind !== 'localisation' || !symbol.id.startsWith('l_english:'))
+            if (symbol.kind !== 'localisation' ||
+                symbol.sourceShadowed ||
+                !symbol.id.startsWith('l_english:'))
                 continue;
             const key = symbol.id.slice('l_english:'.length);
             const previous = localisation.get(key);
@@ -216,7 +277,15 @@ export class ReferenceToolService {
         return context;
     }
 }
-const playerTextPatterns = [
+/** The families file mode checks, the helpers and databases it resolves, and localisation. */
+const fileCheckPatterns = [
+    'events/**/*.txt',
+    'common/decisions/**/*.txt',
+    'common/national_focus/**/*.txt',
+    'common/on_actions/**/*.txt',
+    'common/scripted_effects/**/*.txt',
+    'common/scripted_triggers/**/*.txt',
+    ...Object.keys(implicitTriggerSources).map((folder) => `common/${folder}/*.txt`),
     'localisation/**/*_l_english.yml',
     'common/scripted_localisation/**/*.txt',
 ];

package/dist/hoi4_agent_tools/reference/player-text.js

@@ -7,7 +7,8 @@ const tooltipTriggerBlocks = {
 };
 /** Words that describe the mod's development rather than the game world. */
 const implementationWording = /\b(?:TODO|FIXME|TBD|hard-?coded|newly added|(?:has been|was|been) reworked|placeholder)\b/iu;
-const colourCode = /[§£]/u;
+/** Colour codes; text icons (£) are legible on parchment and stay allowed. */
+const colourCode = '§';
 function blockOf(entry) {
     return entry.value.type === 'block' ? entry.value : undefined;
 }
@@ -61,14 +62,14 @@ export function playerTextFindings(family, document, context) {
             add(node, 'SCRIPT_TEXT_IMPLEMENTATION_WORDING', `${key} (${where(text)}) describes development rather than the game: "${implementationWording.exec(text.value)[0]}"`);
         if (!options.colourFree)
             return;
-        if (colourCode.test(text.value)) {
+        if (text.value.includes(colourCode)) {
             add(node, 'SCRIPT_NEWS_TEXT_COLOUR_CODE', `${key} (${where(text)}) uses a colour code in news or report event text`);
             return;
         }
         for (const name of scriptedTokens(text.value, context))
             for (const branchKey of context.scriptedLocalisation.get(name) ?? []) {
                 const branch = context.localisation.get(branchKey);
-                if (branch !== undefined && colourCode.test(branch.value)) {
+                if (branch?.value.includes(colourCode) === true) {
                     add(node, 'SCRIPT_NEWS_TEXT_COLOUR_CODE', `${key} (${where(text)}) shows [${name}], whose branch ${branchKey} (${where(branch)}) uses a colour code in news or report event text`);
                     return;
                 }

package/dist/hoi4_agent_tools/reference/script-validation.js

@@ -4,6 +4,7 @@ import { ServiceError } from '../core/result.js';
 import { locationFor, parseClausewitz, } from '../core/source/index.js';
 import { repeatedPopupFindings } from './event-popups.js';
 import { playerTextFindings, playerTextPosition } from './player-text.js';
+import { knownMistakeFindings } from './known-mistakes.js';
 import { editDistance } from './suggestions.js';
 import { publicReferenceSection } from './service.js';
 const MAX_COMMANDS = 256;
@@ -487,10 +488,26 @@ export async function validateScript(references, workspace, input, signal, file)
             scope: UNKNOWN_SCOPE,
             line: position.line,
             column: position.column,
-            message: finding.message,
+            message: finding.message.slice(0, 500),
             suggestions: [],
         });
     }
+    const knownMistakes = plan.family === 'snippet' || plan.family === 'unsupported' ? undefined : file?.knownMistakes;
+    if (knownMistakes !== undefined)
+        for (const finding of knownMistakeFindings(plan.family, document, knownMistakes)) {
+            const position = playerTextPosition(documentPath, document.lineIndex, finding);
+            findings.push({
+                code: finding.code,
+                status: finding.rule.severity,
+                command: finding.command.slice(0, 256),
+                kind: 'definition',
+                scope: UNKNOWN_SCOPE,
+                line: position.line,
+                column: position.column,
+                message: finding.message.slice(0, 500),
+                suggestions: [],
+            });
+        }
     const unresolvedCount = findings.filter(({ status }) => status === 'unresolved').length;
     const invalid = findings.some(({ status }) => status === 'error');
     const truncated = visited > commandLimit;
@@ -513,6 +530,7 @@ export async function validateScript(references, workspace, input, signal, file)
             'declared_scope',
             ...(playerTextChecked ? ['player_text'] : []),
             ...(eventPopups === undefined ? [] : ['event_popups']),
+            ...(knownMistakes === undefined ? [] : ['known_mistakes']),
         ],
         parametersChecked: false,
         documentation: {

package/dist/hoi4_agent_tools/reference/service.js

@@ -6,6 +6,7 @@ import { ServiceError } from '../core/result.js';
 import { isWithin } from '../core/workspace.js';
 import { prepareSource, verifySource, readBoundedFile, } from '../core/scanner.js';
 import { decodeSource } from '../core/source/encoding.js';
+import { activeKnownMistakes } from './known-mistakes.js';
 import { readBoundedJsonLines } from './lines.js';
 import { RankingIndex, sectionTerms } from './ranking.js';
 const MAX_FILES = 512;
@@ -544,6 +545,11 @@ export class ReferenceService {
             missing,
             coverage: inventory.coverage,
             skipped: inventory.skipped,
+            knownMistakes: activeKnownMistakes(input.surface).map(({ id, title, fix }) => ({
+                id,
+                title,
+                fix,
+            })),
         };
     }
     publicSection(section) {

package/dist/hoi4_agent_tools/schemas/event.js

@@ -112,25 +112,6 @@ export function validateEventInspectRequest(value, context) {
             message: 'Impact analysis requires impactSubject',
         });
 }
-export const eventInspectRequestSchema = z
-    .object({
-    workspaceId: workspaceIdSchema,
-    mode: eventInspectModeSchema,
-    selector: eventSelectorSchema.optional(),
-    from: eventSelectorSchema.optional(),
-    to: eventSelectorSchema.optional(),
-    direction: eventDirectionSchema.optional(),
-    maxDepth: z.number().int().min(1).max(64).optional(),
-    maxNodes: z.number().int().min(1).max(5_000).optional(),
-    maxEdges: z.number().int().min(1).max(20_000).optional(),
-    expandHelpers: z.boolean().optional(),
-    stateSubject: eventStateSubjectSchema.optional(),
-    impactSubject: eventImpactSubjectSchema.optional(),
-    helperExpansion: helperExpansionRequestSchema.optional(),
-    refresh: z.boolean().optional(),
-})
-    .strict()
-    .superRefine(validateEventInspectRequest);
 export const eventRenderRequestSchema = z
     .object({
     workspaceId: workspaceIdSchema,
@@ -172,3 +153,81 @@ export const eventCompareRequestSchema = z
 })
     .strict()
     .superRefine(validateEventCompareRequest);
+export const eventInspectToolModeSchema = z.enum([...eventInspectModeSchema.options, 'compare']);
+const compareOnlyFields = [
+    'before',
+    'after',
+    'proposedSources',
+    'maxChainNodes',
+    'render',
+    'maxRenderNodes',
+];
+const inspectOnlyFields = [
+    'from',
+    'to',
+    'direction',
+    'maxDepth',
+    'maxNodes',
+    'maxEdges',
+    'expandHelpers',
+    'stateSubject',
+    'impactSubject',
+    'helperExpansion',
+];
+/**
+ * Inspection and comparison share one tool: mode compare diffs a cached, artifact or proposed
+ * event graph against another, every other mode analyzes the current graph.
+ */
+export const eventInspectRequestSchema = z
+    .object({
+    workspaceId: workspaceIdSchema,
+    mode: eventInspectToolModeSchema,
+    selector: eventSelectorSchema.optional(),
+    from: eventSelectorSchema.optional(),
+    to: eventSelectorSchema.optional(),
+    direction: eventDirectionSchema.optional(),
+    maxDepth: z.number().int().min(1).max(64).optional(),
+    maxNodes: z.number().int().min(1).max(5_000).optional(),
+    maxEdges: z.number().int().min(1).max(20_000).optional(),
+    expandHelpers: z.boolean().optional(),
+    stateSubject: eventStateSubjectSchema.optional(),
+    impactSubject: eventImpactSubjectSchema.optional(),
+    helperExpansion: helperExpansionRequestSchema.optional(),
+    before: eventGraphReferenceSchema.optional(),
+    after: eventGraphReferenceSchema.optional(),
+    proposedSources: z.array(eventProposedSourceSchema).min(1).max(64).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(),
+})
+    .strict()
+    .superRefine(validateEventInspectToolRequest);
+export function validateEventInspectToolRequest(value, context) {
+    const compare = value.mode === 'compare';
+    for (const field of compare ? inspectOnlyFields : compareOnlyFields)
+        if (value[field] !== undefined)
+            context.addIssue({
+                code: 'custom',
+                path: [field],
+                message: compare
+                    ? `${field} is not used by mode compare`
+                    : `${field} is used only by mode compare`,
+            });
+    if (compare)
+        validateEventCompareRequest(value, context);
+    else
+        validateEventInspectRequest(value, context);
+}
+/** Split an inspect request into a comparison or an analysis of the current graph. */
+export function splitEventInspectRequest(input) {
+    const { mode, ...rest } = input;
+    if (mode === 'compare') {
+        const request = { workspaceId: rest.workspaceId };
+        for (const field of [...compareOnlyFields, 'selector', 'refresh'])
+            if (rest[field] !== undefined)
+                request[field] = rest[field];
+        return { compare: true, request: eventCompareRequestSchema.parse(request) };
+    }
+    return { compare: false, request: { ...rest, mode } };
+}

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

@@ -77,10 +77,20 @@ export const focusRenderRequestSchema = z
     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(),
+    png: z
+        .boolean()
+        .optional()
+        .describe('Default true: add a PNG with decoded source icons. False returns only the faster HTML, SVG and JSON.'),
 })
     .strict()
     .superRefine((value, context) => {
     const mode = value.mode ?? 'national';
+    if (value.png === false && (value.cropFocusIds?.length ?? 0) > 0)
+        context.addIssue({
+            code: 'custom',
+            path: ['cropFocusIds'],
+            message: 'cropFocusIds produce PNG crops; omit png or set it to true',
+        });
     const invalid = mode === 'national'
         ? [
             ['paletteId', value.paletteId],

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;
+    }
+}