hoi4-agent-tools 3.8.0 → 3.9.0

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

@@ -2,9 +2,158 @@ import path from 'node:path';
 import { hashCanonical } from '../core/canonical.js';
 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 { editDistance } from './suggestions.js';
 import { publicReferenceSection } from './service.js';
 const MAX_COMMANDS = 256;
+const MAX_FILE_COMMANDS = 50_000;
+/** A block whose scope the file's structure does not determine; scope checks are skipped. */
+const UNKNOWN_SCOPE = 'unknown';
+/**
+ * Scope links from the wiki Scopes page: the scopes each link is usable in and the scope it
+ * enters. The engine accepts these keys in any letter case.
+ */
+const scopeLinks = {
+    owner: { from: ['state', 'character', 'combatant'], to: 'country' },
+    controller: { from: ['state'], to: 'country' },
+    capital_scope: { from: ['country'], to: 'state' },
+    overlord: { from: ['country'], to: 'country' },
+    faction_leader: { from: ['country'], to: 'country' },
+};
+const eventScopes = {
+    country_event: 'country',
+    news_event: 'country',
+    state_event: 'state',
+    unit_leader_event: 'character',
+    operative_leader_event: 'character',
+};
+const optionMetadata = new Set([
+    'name',
+    'ai_chance',
+    'original_recipient_only',
+    'highlight_states',
+    'is_triggered_only',
+]);
+const decisionTriggers = new Set([
+    'allowed',
+    'visible',
+    'available',
+    'cancel_trigger',
+    'remove_trigger',
+    'activation',
+]);
+const decisionEffects = new Set([
+    'complete_effect',
+    'remove_effect',
+    'timeout_effect',
+    'cancel_effect',
+]);
+const focusTriggers = new Set(['available', 'bypass', 'cancel', 'allow_branch']);
+const focusEffects = new Set([
+    'completion_reward',
+    'select_effect',
+    'cancel_effect',
+    'bypass_effect',
+]);
+function blockOf(entry) {
+    return entry.type === 'assignment' && entry.value.type === 'block' ? entry.value : undefined;
+}
+/**
+ * The effect and trigger bodies of a mod file, with the scope its structure fixes. Families
+ * whose scope depends on the caller, such as scripted helpers and on actions, are checked
+ * without scope rules. An unrecognized family yields no roots.
+ */
+export function scriptRoots(relativePath, document) {
+    const file = relativePath.replaceAll('\\', '/').toLowerCase();
+    const roots = [];
+    const add = (block, kind, scope) => {
+        if (block !== undefined)
+            roots.push({ block, kind, scope });
+    };
+    const top = document.root.entries.filter((entry) => entry.type === 'assignment');
+    if (file.startsWith('events/')) {
+        for (const event of top) {
+            const scope = eventScopes[event.key.value];
+            const body = blockOf(event);
+            if (scope === undefined || body === undefined)
+                continue;
+            for (const entry of body.entries) {
+                if (entry.type !== 'assignment')
+                    continue;
+                const key = entry.key.value;
+                if (key === 'trigger' || key === 'show_major')
+                    add(blockOf(entry), 'trigger', scope);
+                else if (key === 'immediate' || key === 'after')
+                    add(blockOf(entry), 'effect', scope);
+                else if (key === 'option') {
+                    const option = blockOf(entry);
+                    if (option === undefined)
+                        continue;
+                    const effects = option.entries.filter((child) => child.type !== 'assignment' ||
+                        (child.key.value !== 'trigger' && !optionMetadata.has(child.key.value)));
+                    for (const child of option.entries)
+                        if (child.type === 'assignment' && child.key.value === 'trigger')
+                            add(blockOf(child), 'trigger', scope);
+                    if (effects.length > 0)
+                        add({ ...option, entries: effects }, 'effect', scope);
+                }
+            }
+        }
+        return { family: 'events', roots };
+    }
+    if (file.startsWith('common/decisions/') && !file.startsWith('common/decisions/categories/')) {
+        for (const category of top)
+            for (const decision of blockOf(category)?.entries ?? []) {
+                const body = blockOf(decision);
+                if (body === undefined)
+                    continue;
+                for (const entry of body.entries) {
+                    if (entry.type !== 'assignment')
+                        continue;
+                    if (decisionTriggers.has(entry.key.value))
+                        add(blockOf(entry), 'trigger', 'country');
+                    else if (entry.key.value === 'target_trigger')
+                        add(blockOf(entry), 'trigger', UNKNOWN_SCOPE);
+                    else if (decisionEffects.has(entry.key.value))
+                        add(blockOf(entry), 'effect', 'country');
+                }
+            }
+        return { family: 'decisions', roots };
+    }
+    if (file.startsWith('common/national_focus/')) {
+        const focuses = top.flatMap((entry) => entry.key.value === 'shared_focus'
+            ? [entry]
+            : entry.key.value === 'focus_tree'
+                ? (blockOf(entry)?.entries ?? []).filter((child) => child.type === 'assignment' && child.key.value === 'focus')
+                : []);
+        for (const focus of focuses)
+            for (const entry of blockOf(focus)?.entries ?? []) {
+                if (entry.type !== 'assignment')
+                    continue;
+                if (focusTriggers.has(entry.key.value))
+                    add(blockOf(entry), 'trigger', 'country');
+                else if (focusEffects.has(entry.key.value))
+                    add(blockOf(entry), 'effect', 'country');
+            }
+        return { family: 'national_focus', roots };
+    }
+    if (file.startsWith('common/scripted_effects/') || file.startsWith('common/scripted_triggers/')) {
+        const kind = file.startsWith('common/scripted_effects/') ? 'effect' : 'trigger';
+        for (const helper of top)
+            add(blockOf(helper), kind, UNKNOWN_SCOPE);
+        return { family: kind === 'effect' ? 'scripted_effects' : 'scripted_triggers', roots };
+    }
+    if (file.startsWith('common/on_actions/')) {
+        for (const container of top)
+            for (const action of blockOf(container)?.entries ?? [])
+                for (const entry of blockOf(action)?.entries ?? [])
+                    if (entry.type === 'assignment' && entry.key.value === 'effect')
+                        add(blockOf(entry), 'effect', UNKNOWN_SCOPE);
+        return { family: 'on_actions', roots };
+    }
+    return { family: 'unsupported', roots };
+}
 const booleanCommands = new Set(['AND', 'OR', 'NOT', 'XOR', 'NAND', 'NOR']);
 const containers = new Set([
     'and',
@@ -24,14 +173,21 @@ const iteratorParameters = new Set([
     'count',
 ]);
 /** Check only rules explicitly available from one selected documentation authority. */
-export async function validateScript(references, workspace, input, signal) {
-    if (Buffer.byteLength(input.source, 'utf8') > 64_000)
+export async function validateScript(references, workspace, input, signal, file) {
+    if (file === undefined && Buffer.byteLength(input.source ?? '', 'utf8') > 64_000)
         throw new ServiceError('SCRIPT_SOURCE_TOO_LARGE', 'Snippet exceeds 64000 UTF-8 bytes');
     const inventory = await references.inventory(workspace, signal, [input.documentation]);
     const catalogs = { effect: new Map(), trigger: new Map() };
     const sources = new Map();
+    const dynamicVariables = new Set();
+    // Generic triggers such as `building_count_trigger` are written with a listed name as the
+    // key (`arms_factory > 2`); each listed name checks as that documented trigger.
+    const implicitNames = new Map();
     for (const section of inventory.sections) {
         const filename = path.basename(section.path).toLowerCase();
+        if (filename === 'dynamic_variables_documentation.md' &&
+            /^[a-z_][a-z0-9_]{0,255}$/u.test(section.heading))
+            dynamicVariables.add(section.heading);
         const match = /^(effects?|triggers?)_(?:documentation|docs)\.(?:md|log)$/u.exec(filename);
         if (match === null)
             continue;
@@ -48,6 +204,12 @@ export async function validateScript(references, workspace, input, signal) {
                 .filter(Boolean)),
         ].sort();
         const kind = match[1].startsWith('effect') ? 'effect' : 'trigger';
+        const body = section.lines.join('\n');
+        const listed = /^Supported (?!Scopes|Targets)[A-Za-z ]+:\s*([a-z0-9_,\s]+?)\.?\s*$/mu.exec(body);
+        if (kind === 'trigger' && listed !== null && /^Usage:\s*<[A-Za-z]+>/mu.test(body))
+            for (const name of listed[1].split(/[,\s]+/u).filter(Boolean))
+                if (!implicitNames.has(name))
+                    implicitNames.set(name, section.heading);
         const previous = catalogs[kind].get(section.heading);
         const reference = publicReferenceSection(section);
         if (previous !== undefined) {
@@ -56,7 +218,15 @@ export async function validateScript(references, workspace, input, signal) {
         else
             catalogs[kind].set(section.heading, { reference, scopes, conflict: false });
     }
-    const document = parseClausewitz(Buffer.from(input.source, 'utf8'), 'snippet');
+    for (const [name, heading] of [...implicitNames, ...(file?.implicitTriggers ?? [])]) {
+        const signature = catalogs.trigger.get(heading);
+        if (signature !== undefined && !catalogs.trigger.has(name))
+            catalogs.trigger.set(name, signature);
+    }
+    const documentPath = file?.path ?? 'snippet';
+    const document = parseClausewitz(file?.bytes ?? Buffer.from(input.source ?? '', 'utf8'), documentPath);
+    const commandLimit = file === undefined ? MAX_COMMANDS : MAX_FILE_COMMANDS;
+    let rootScope = input.scope ?? UNKNOWN_SCOPE;
     const findings = [];
     let visited = 0;
     let checkedCommands = 0;
@@ -71,7 +241,11 @@ export async function validateScript(references, workspace, input, signal) {
         bindings.set(binding.name, binding.scope);
     }
     const report = (entry, kind, scope, details) => {
-        const position = locationFor('snippet', document.lineIndex, entry.start, entry.end).start;
+        const position = locationFor(documentPath, document.lineIndex, entry.start, entry.end).start;
+        // A file check lists only problems; matching commands are counted, not itemized.
+        if (file !== undefined &&
+            (details.status === 'supported' || details.code === 'SCRIPT_ARGUMENT_BLOCK_UNCHECKED'))
+            return;
         findings.push({
             ...details,
             command: entry.key.value.slice(0, 256),
@@ -86,8 +260,8 @@ export async function validateScript(references, workspace, input, signal) {
             code: diagnostic.code,
             status: 'error',
             command: '',
-            kind: input.kind,
-            scope: input.scope,
+            kind: input.kind ?? 'effect',
+            scope: input.scope ?? UNKNOWN_SCOPE,
             line: diagnostic.location?.start.line ?? 1,
             column: diagnostic.location?.start.column ?? 1,
             message: diagnostic.message.slice(0, 500),
@@ -96,11 +270,11 @@ export async function validateScript(references, workspace, input, signal) {
     const walk = (block, kind, scope, previous) => {
         for (const entry of block.entries) {
             signal?.throwIfAborted();
-            if (++visited > MAX_COMMANDS) {
+            if (++visited > commandLimit) {
                 return;
             }
             if (entry.type !== 'assignment') {
-                const position = locationFor('snippet', document.lineIndex, entry.start, entry.end).start;
+                const position = locationFor(documentPath, document.lineIndex, entry.start, entry.end).start;
                 findings.push({
                     code: 'SCRIPT_EXPECTED_COMMAND',
                     status: 'error',
@@ -119,7 +293,7 @@ export async function validateScript(references, workspace, input, signal) {
                 continue;
             const name = booleanCommands.has(raw) ? raw.toLowerCase() : raw;
             const explicitScope = raw === 'ROOT'
-                ? input.scope
+                ? rootScope
                 : raw === 'THIS'
                     ? scope
                     : raw === 'PREV'
@@ -136,8 +310,57 @@ export async function validateScript(references, workspace, input, signal) {
                 walk(entry.value, kind, explicitScope ?? fixedScope, scope);
                 continue;
             }
+            const link = entry.value.type === 'block' ? scopeLinks[raw.toLowerCase()] : undefined;
+            if (link !== undefined && entry.value.type === 'block') {
+                checkedCommands++;
+                if (scope !== UNKNOWN_SCOPE && !link.from.includes(scope))
+                    report(entry, kind, scope, {
+                        code: 'SCRIPT_SCOPE_LINK_WRONG_SCOPE',
+                        status: 'error',
+                        message: `${raw} is usable only within ${link.from.join(', ')} scope`,
+                        suggestions: [],
+                    });
+                walk(entry.value, kind, link.to, scope);
+                continue;
+            }
+            // A file has no caller to declare FROM, chained links or targets; their blocks are
+            // still checked for command kinds, without scope rules.
+            if (file !== undefined &&
+                entry.value.type === 'block' &&
+                (/^(?:root|this|prev|from)(?:\.(?:root|this|prev|from))*$/iu.test(raw) ||
+                    /^(?:event_target|var|mio|sp):/u.test(raw))) {
+                const keyword = raw.toUpperCase();
+                walk(entry.value, kind, keyword === 'ROOT'
+                    ? rootScope
+                    : keyword === 'THIS'
+                        ? scope
+                        : keyword === 'PREV'
+                            ? (previous ?? UNKNOWN_SCOPE)
+                            : UNKNOWN_SCOPE, scope);
+                continue;
+            }
             const signature = catalogs[kind].get(name);
-            if (signature === undefined) {
+            if (signature === undefined && file?.helpers[kind].has(name) === true) {
+                // A scripted helper of the mod; its own file is checked separately.
+                checkedCommands++;
+                continue;
+            }
+            // Only a scalar comparison (`num_owned_states > 1`) misuses a dynamic variable; a block
+            // with that key is a scope or helper the catalog does not describe.
+            if (signature === undefined &&
+                kind === 'trigger' &&
+                entry.value.type !== 'block' &&
+                dynamicVariables.has(name)) {
+                report(entry, kind, scope, {
+                    code: 'SCRIPT_DYNAMIC_VARIABLE_AS_TRIGGER',
+                    status: 'error',
+                    message: `${name} is a documented dynamic variable, not a trigger; compare it with check_variable`,
+                    suggestions: ['check_variable'],
+                });
+                continue;
+            }
+            // else_if and else are control flow even where the documentation lists only `if`.
+            if (signature === undefined && !conditionals.has(name) && !containers.has(name)) {
                 const other = catalogs[kind === 'effect' ? 'trigger' : 'effect'].get(name);
                 const suggestions = name.length > 128
                     ? []
@@ -161,22 +384,26 @@ export async function validateScript(references, workspace, input, signal) {
                 continue;
             }
             checkedCommands++;
-            const wrongScope = !signature.scopes.includes('any') && !signature.scopes.includes(scope);
-            report(entry, kind, scope, {
-                code: signature.conflict
-                    ? 'SCRIPT_DOCUMENTATION_CONFLICT'
-                    : wrongScope
-                        ? 'SCRIPT_COMMAND_WRONG_SCOPE'
-                        : 'SCRIPT_COMMAND_SUPPORTED',
-                status: signature.conflict ? 'unresolved' : wrongScope ? 'error' : 'supported',
-                suggestions: [],
-                reference: signature.reference,
-                message: signature.conflict
-                    ? 'Conflicting supported scopes in the selected documentation'
-                    : wrongScope
-                        ? `Supported scopes: ${signature.scopes.join(', ')}`
-                        : 'Command kind and declared scope match the selected documentation',
-            });
+            if (signature !== undefined) {
+                const wrongScope = scope !== UNKNOWN_SCOPE &&
+                    !signature.scopes.includes('any') &&
+                    !signature.scopes.includes(scope);
+                report(entry, kind, scope, {
+                    code: signature.conflict
+                        ? 'SCRIPT_DOCUMENTATION_CONFLICT'
+                        : wrongScope
+                            ? 'SCRIPT_COMMAND_WRONG_SCOPE'
+                            : 'SCRIPT_COMMAND_SUPPORTED',
+                    status: signature.conflict ? 'unresolved' : wrongScope ? 'error' : 'supported',
+                    suggestions: [],
+                    reference: signature.reference,
+                    message: signature.conflict
+                        ? 'Conflicting supported scopes in the selected documentation'
+                        : wrongScope
+                            ? `Supported scopes: ${signature.scopes.join(', ')}`
+                            : 'Command kind and declared scope match the selected documentation',
+                });
+            }
             const iterator = /^(?:every|random|any|all)_(?:(?:owned|controlled|neighbor)_)?(state|country)$/u.exec(name);
             if (entry.value.type !== 'block') {
                 if (containers.has(name) || conditionals.has(name) || iterator !== null)
@@ -185,7 +412,7 @@ export async function validateScript(references, workspace, input, signal) {
                         status: 'error',
                         message: 'This control command requires a block',
                         suggestions: [],
-                        reference: signature.reference,
+                        ...(signature === undefined ? {} : { reference: signature.reference }),
                     });
                 continue;
             }
@@ -223,25 +450,70 @@ export async function validateScript(references, workspace, input, signal) {
                     status: 'unresolved',
                     message: 'Native argument block is not validated from prose documentation; read the cited syntax before use',
                     suggestions: [],
-                    reference: signature.reference,
+                    ...(signature === undefined ? {} : { reference: signature.reference }),
                 });
             }
         }
     };
+    const plan = file === undefined
+        ? {
+            family: 'snippet',
+            roots: [{ block: document.root, kind: input.kind, scope: input.scope }],
+        }
+        : scriptRoots(file.relativePath, document);
     if (document.diagnostics.every(({ severity }) => severity !== 'error' && severity !== 'blocker'))
-        walk(document.root, input.kind, input.scope);
+        for (const root of plan.roots) {
+            rootScope = root.scope;
+            walk(root.block, root.kind, root.scope);
+        }
+    const playerText = plan.family === 'snippet' ? undefined : file?.playerText;
+    const playerTextChecked = playerText !== undefined;
+    const eventPopups = plan.family === 'snippet' ? undefined : file?.eventPopups;
+    const warnings = [
+        ...(playerText === undefined ? [] : playerTextFindings(plan.family, document, playerText)),
+        ...(eventPopups === undefined ? [] : repeatedPopupFindings(document, eventPopups)),
+    ];
+    for (const finding of warnings) {
+        const position = playerTextPosition(documentPath, document.lineIndex, finding);
+        findings.push({
+            code: finding.code,
+            status: 'warning',
+            command: finding.command.slice(0, 256),
+            kind: finding.code === 'SCRIPT_FLAG_TOOLTIP_UNLOCALISED'
+                ? 'trigger'
+                : finding.code === 'SCRIPT_EVENT_POPUP_REPEATED'
+                    ? 'effect'
+                    : 'text',
+            scope: UNKNOWN_SCOPE,
+            line: position.line,
+            column: position.column,
+            message: finding.message,
+            suggestions: [],
+        });
+    }
     const unresolvedCount = findings.filter(({ status }) => status === 'unresolved').length;
     const invalid = findings.some(({ status }) => status === 'error');
-    const truncated = visited > MAX_COMMANDS;
-    const incomplete = unresolvedCount > 0 || truncated || inventory.skipped > 0 || catalogs[input.kind].size === 0;
-    const order = { error: 0, unresolved: 1, supported: 2 };
+    const truncated = visited > commandLimit;
+    const unknownScopeRoots = plan.roots.filter(({ scope }) => scope === UNKNOWN_SCOPE).length;
+    const incomplete = unresolvedCount > 0 ||
+        truncated ||
+        inventory.skipped > 0 ||
+        (file === undefined ? catalogs[input.kind].size === 0 : plan.roots.length === 0) ||
+        unknownScopeRoots > 0;
+    const order = { error: 0, unresolved: 1, warning: 2, supported: 3 };
     findings.sort((a, b) => order[a.status] - order[b.status] ||
         a.line - b.line ||
         a.column - b.column ||
         a.code.localeCompare(b.code, 'en'));
     const result = {
         valid: invalid ? false : incomplete ? null : true,
-        checksPerformed: ['syntax', 'command_kind', 'declared_scope'],
+        checksPerformed: [
+            'syntax',
+            'command_kind',
+            'declared_scope',
+            ...(playerTextChecked ? ['player_text'] : []),
+            ...(eventPopups === undefined ? [] : ['event_popups']),
+        ],
         parametersChecked: false,
         documentation: {
             source: input.documentation,
@@ -257,6 +529,16 @@ export async function validateScript(references, workspace, input, signal) {
         unresolvedCount,
         truncated,
         argumentBlocksUnchecked,
+        ...(file === undefined
+            ? {}
+            : {
+                file: {
+                    path: file.path,
+                    family: plan.family,
+                    roots: plan.roots.length,
+                    unknownScopeRoots,
+                },
+            }),
     };
     while (Buffer.byteLength(JSON.stringify(result), 'utf8') > 16_000 && result.findings.length > 1)
         result.findings.pop();

package/dist/hoi4_agent_tools/reference/source-locate.js

@@ -19,7 +19,7 @@ function samePath(left, right) {
     return process.platform === 'win32' ? left.toLowerCase() === right.toLowerCase() : left === right;
 }
 /** Resolve a display, relative, or absolute path to one scanned file, preferring the active layer. */
-function selectFile(snapshot, requested) {
+export function selectFile(snapshot, requested) {
     const normalized = requested.replaceAll('\\', '/').replace(/^\.\//u, '');
     const absolute = path.isAbsolute(requested) ? path.resolve(requested) : undefined;
     const candidates = [...snapshot.index.files.values()].filter((file) => file.displayPath === normalized ||

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

@@ -8,7 +8,21 @@ import { backgroundRequestKeySchema, workspaceIdSchema, workspaceRelativePathSch
 function compact(schema, description) {
     return z.unknown().describe(description).pipe(schema);
 }
-const compactGuiScenarioSchema = compact(GuiPreviewScenarioSchema, 'GUI preview scenario; optional date and controls {stateId: controllerTag}.');
+/**
+ * Published scenario shape: the required `id` and the fields that decide visibility, with the
+ * rest named in the description. Every field is validated by the full scenario schema.
+ */
+const compactGuiScenarioSchema = z
+    .looseObject({
+    id: z.string(),
+    date: z.string().optional(),
+    closedFlags: z.boolean().optional(),
+})
+    .describe('Also flags {name: bool}, variables {name: number}, controls {stateId: tag}, values, visibility (docs/gui.md). closedFlags: undeclared flags are unset.')
+    .transform((value) => value)
+    .pipe(GuiPreviewScenarioSchema);
+/** Related and comparison scenarios repeat the primary scenario's published shape. */
+const compactRelatedScenarioSchema = compact(GuiPreviewScenarioSchema, 'Same shape as scenario.');
 const compactGeneratedScenarioOptionsSchema = compact(GuiGeneratedScenarioOptionsSchema, 'GUI generated-scenario options.');
 const compactGuiHelperSchema = compact(GuiHelperDocumentSchema, 'GUI helper document.');
 export const guiPreviewStateSchema = z.enum([
@@ -32,7 +46,7 @@ export const guiInspectRequestSchema = z
     workspaceId: workspaceIdSchema,
     windowName: z.string().min(1).max(256).optional(),
     scenario: compactGuiScenarioSchema.optional(),
-    relatedScenarios: z.array(compactGuiScenarioSchema).max(32).optional(),
+    relatedScenarios: z.array(compactRelatedScenarioSchema).max(32).optional(),
     generatedScenarios: compactGeneratedScenarioOptionsSchema.optional(),
 })
     .strict()
@@ -79,9 +93,9 @@ export const guiRenderRequestSchema = z
     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(),
+    relatedScenarios: z.array(compactRelatedScenarioSchema).max(32).optional(),
     generatedScenarios: compactGeneratedScenarioOptionsSchema.optional(),
-    comparisonScenario: compactGuiScenarioSchema.optional(),
+    comparisonScenario: compactRelatedScenarioSchema.optional(),
     sourceBaseline: z
         .object({
         relativePath: workspaceRelativePathSchema,

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

@@ -18,9 +18,12 @@ const scope = z.enum([
 export const scriptValidateRequestSchema = z
     .object({
     workspaceId: workspaceIdSchema,
-    source: z.string().min(1).max(64_000),
-    kind: z.enum(['effect', 'trigger']),
-    scope,
+    /** Snippet mode: an effect or trigger body checked under `kind` and `scope`. */
+    source: z.string().min(1).max(64_000).optional(),
+    /** File mode: a scanned mod file whose blocks are checked under the scope its structure fixes. */
+    path: z.string().trim().min(1).max(4096).optional(),
+    kind: z.enum(['effect', 'trigger']).optional(),
+    scope: scope.optional(),
     documentation: z.enum(['game_doc', 'script_doc']).default('game_doc'),
     bindings: z
         .array(z.object({ name: z.string().min(1).max(256), scope }).strict())
@@ -28,11 +31,32 @@ export const scriptValidateRequestSchema = z
         .default([]),
     limit: z.number().int().min(1).max(32).default(12),
 })
-    .strict();
+    .strict()
+    .superRefine((value, context) => {
+    if ((value.source === undefined) === (value.path === undefined))
+        context.addIssue({
+            code: 'custom',
+            path: ['source'],
+            message: 'Provide either source with kind and scope, or a mod file path',
+        });
+    if (value.source !== undefined && (value.kind === undefined || value.scope === undefined))
+        context.addIssue({
+            code: 'custom',
+            path: ['kind'],
+            message: 'A snippet check requires kind and scope',
+        });
+    if (value.path !== undefined &&
+        (value.kind !== undefined || value.scope !== undefined || value.bindings.length > 0))
+        context.addIssue({
+            code: 'custom',
+            path: ['path'],
+            message: 'A file check infers kinds and scopes from the file structure',
+        });
+});
 export const scriptValidateDataSchema = z
     .object({
     valid: z.boolean().nullable(),
-    checksPerformed: z.array(z.enum(['syntax', 'command_kind', 'declared_scope'])),
+    checksPerformed: z.array(z.enum(['syntax', 'command_kind', 'declared_scope', 'player_text', 'event_popups'])),
     parametersChecked: z.literal(false),
     documentation: z
         .object({
@@ -47,9 +71,9 @@ export const scriptValidateDataSchema = z
         .array(z
         .object({
         code: z.string().max(80),
-        status: z.enum(['supported', 'error', 'unresolved']),
+        status: z.enum(['supported', 'error', 'unresolved', 'warning']),
         command: z.string().max(256),
-        kind: z.enum(['effect', 'trigger']),
+        kind: z.enum(['effect', 'trigger', 'text']),
         scope: z.string().max(64),
         line: z.number().int().min(1),
         column: z.number().int().min(1),
@@ -65,5 +89,14 @@ export const scriptValidateDataSchema = z
     unresolvedCount: z.number().int().min(0),
     truncated: z.boolean(),
     argumentBlocksUnchecked: z.number().int().min(0),
+    file: z
+        .object({
+        path: z.string().max(4096),
+        family: z.string().max(64),
+        roots: z.number().int().min(0),
+        unknownScopeRoots: z.number().int().min(0),
+    })
+        .strict()
+        .optional(),
 })
     .strict();

package/dist/hoi4_agent_tools/version.js

@@ -1,6 +1,6 @@
 import { LATEST_PROTOCOL_VERSION } from '@modelcontextprotocol/sdk/types.js';
 export const PACKAGE_NAME = 'hoi4-agent-tools';
-export const PACKAGE_VERSION = '3.8.0';
+export const PACKAGE_VERSION = '3.9.0';
 export const MCP_PROTOCOL_VERSION = LATEST_PROTOCOL_VERSION;
 export const CONFIG_VERSION = 1;
 export const TRANSACTION_VERSION = 1;

package/docs/gui.md

@@ -184,6 +184,31 @@ Source or scenario `enabled = false` selects disabled appearance and removes the
 
 The renderer does not run the game engine. Each render includes a fidelity report that separates fields it models from fields it approximates, ignores, cannot resolve, or does not support. Treat that report as part of the review.
 
+### Scenario fields
+
+Every `scenario` needs an `id`, a short label such as `"usa_1936"`. The other fields describe the game state the window is drawn under:
+
+| Field                                        | Meaning                                                                                                                                                                                        |
+| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `date`                                       | Game date, `"1936.1.1"`.                                                                                                                                                                       |
+| `controls`                                   | State controllers, `{"64": "GER"}`.                                                                                                                                                            |
+| `flags`                                      | Flags on the viewing country, `{"show_settings_page": true}`.                                                                                                                                  |
+| `closedFlags`                                | `true` treats every flag not listed in `flags` as unset, as on a country that never received it. Without it, an undeclared flag is unknown and every condition that reads it stays unresolved. |
+| `variables`                                  | Variables on the viewing country, `{"settings_page": 1}`.                                                                                                                                      |
+| `values`                                     | Exact runtime values for localisation tokens and scripted GUI properties, keyed as they appear in source.                                                                                      |
+| `visibility`                                 | Forced visibility by element or scripted GUI name, `{"settings_page_events": false}`; it overrides evaluated triggers.                                                                         |
+| `scopes`                                     | Named scope bindings such as `FROM` with their own state.                                                                                                                                      |
+| `resolution`, `uiScale`, `state`, `language` | Screen size, in-game UI scale, preview element state, and localisation language.                                                                                                               |
+| `background`                                 | `"transparent"` renders without the preview backdrop, so pixels the window does not cover are fully transparent in every PNG.                                                                  |
+
+A scripted GUI `visible` or `<element>_visible` trigger that the scenario decides hides or shows its element exactly.
+For compositing, each visible element is its own `<g>` group in the full SVG, with an `id` that matches the element in `layout.json`, which also records every element's box.
+A trigger the scenario cannot decide leaves the element drawn and lists it in the fidelity report as unresolved, so pages that the game shows one at a time can overlap in the preview.
+For tabbed windows, set the flags or variables of the page to show and `closedFlags: true`, then render each page as its own scenario through `relatedScenarios`.
+`GUI_UNRESOLVED_VISIBILITY_OVERLAP` names each overlapping pair drawn together for that reason.
+`GUI_NEAR_CENTRE_OFFSET` names an element whose horizontal centre is between half a pixel and 3 pixels from its parent's centre, which usually means it was meant to be centred.
+Scripted localisation (`defined_text`) used by the window resolves to its first branch whose trigger the scenario decides as true, as long as every earlier branch is decided false; otherwise the token renders as `[dynamic_loc]`. A value in `values` always takes precedence.
+
 The generated primary view replaces discovered numeric and text runtime tokens with plausible values. Set `generatedScenarios.preservePlaceholder` to `true`, or disable generation, when the same run should also show unresolved numeric values such as `[?variable|format]` as `[X]` and unresolved text-returning scripted or scoped localisation such as `[GetStatusText]`, `[FROM.GetName]`, and `[?leader_scope.GetName]` as `[dynamic_loc]`. Put `variable` or `GetStatusText` in the supplied scenario's `values` object when an exact value matters; explicit values always take precedence over generated ones and can drive the related meter or state-dependent controls. Supported HOI4 `§` localisation colour controls use the active font's palette and `§!` restores the face colour.
 
 A rewrite stops if malformed or unsupported GUI script makes the requested change ambiguous. Frame-sheet animation, nine-slice tiling, progress composition, masking, and the primary and secondary textures referenced by vanilla GFX definitions render offline. Font selection follows mod/game load order and preview language, accepts Paradox hex and numeric color declarations, and uses the supplied HOI4 bitmap or outline font assets without requiring host font installation. Shader operations outside the supported colour subset, hardcoded controls, and dynamic values that are not supplied by a scenario remain fidelity-report entries; an unexecuted shader never hides its resolved base texture.

package/docs/jobs.md

@@ -51,6 +51,14 @@ A running cancellation is observed by the isolated worker; if a rewrite has alre
 Cancelling an ordinary synchronous call prevents admission when possible and otherwise requests cooperative cancellation of its durable job.
 Closing the originating connection does not cancel an accepted native task.
 
+A worker busy in long synchronous analysis cannot observe its own cancellation, so the server that started it also supervises read-only jobs.
+A read-only job still running `jobCancelGraceSeconds` (default 10) after cancellation is stopped and settles as cancelled.
+A read-only job still running `jobDeadlineSeconds` (default 1,800) after it was dispatched is stopped and fails with `JOB_DEADLINE_EXCEEDED`; narrow its selector or limits, or raise the setting in the server configuration.
+Rewrite jobs are never stopped this way, because their transaction journal owns write recovery; they keep cooperative cancellation and reconciliation.
+Supervision belongs to the server process that dispatched the worker. A read-only worker whose dispatching server has exited enforces the same deadline itself and then exits; a rewrite worker keeps running until it finishes.
+`jobWorkerMaxHeapMiB` sets a V8 heap ceiling for each worker; without it, workers use Node's default.
+At most `maxSharedTools` (default 4) workers and expensive calls run at once across every server process that shares a `serverStateRoot`; further work waits for capacity.
+
 Read-only jobs stage a source-revision-bound result checkpoint before terminal publication.
 If a worker or server stops after that checkpoint, a later authorized process publishes the retained result without rerunning the operation.
 Event and technology helper expansion also saves an authenticated intermediate frontier with its exact source revision and traversal contract.