hoi4-agent-tools 3.4.1 → 3.5.0

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

@@ -319,6 +319,22 @@ function candidatesFor(context, adapterId) {
     }
 }
 function sourceContexts(snapshot, source) {
+    if (source.snapshotPath !== undefined) {
+        if (source.path === undefined ||
+            source.expectedSourceHash === undefined ||
+            source.inlineClausewitz !== undefined ||
+            source.virtualPatch !== undefined)
+            throw new ServiceError('PROBABILITY_SNAPSHOT_CONTRACT_REQUIRED', 'Frozen source requires a logical path and exact snapshot hash');
+        const snapshotPath = normalized(source.snapshotPath);
+        const selected = snapshot.files.filter((file) => file.shadowedBy === undefined && normalized(file.relativePath) === snapshotPath);
+        if (selected.length !== 1)
+            throw new ServiceError('PROBABILITY_SNAPSHOT_NOT_FOUND', 'Frozen source must resolve to one active authorized file', { snapshotPath: source.snapshotPath });
+        const original = selected[0];
+        if (original.sha256 !== source.expectedSourceHash)
+            throw new ServiceError('PROBABILITY_SOURCE_STALE', 'Frozen probability source hash is stale', { expectedSourceHash: source.expectedSourceHash, actualSourceHashes: [original.sha256] });
+        const file = { ...original, relativePath: normalized(source.path) };
+        return [{ file, document: parseClausewitz(file.bytes, file.displayPath) }];
+    }
     if (source.inlineClausewitz !== undefined || source.virtualPatch !== undefined) {
         const text = source.virtualPatch ?? source.inlineClausewitz ?? '';
         const bytes = Buffer.from(text, 'utf8');

package/dist/hoi4_agent_tools/probability/value-evaluator.js

@@ -198,6 +198,7 @@ export function evaluateValueBlock(block, candidate, scenario, definitions, init
     const trace = [];
     const unresolved = [];
     const referencedProvenance = [];
+    const { candidateOverrides: _eligibilityOverrides, ...modifierScenario } = scenario;
     if (block === undefined)
         return { value: initial, interval: current, trace, unresolved };
     for (const assignment of assignments(block)) {
@@ -257,7 +258,7 @@ export function evaluateValueBlock(block, candidate, scenario, definitions, init
         if (assignment.key.value !== 'modifier')
             continue;
         const modifier = assignment.value;
-        const condition = evaluateTriggerBlock(conditionBlock(modifier), scenario, candidate, definitions);
+        const condition = evaluateTriggerBlock(conditionBlock(modifier), modifierScenario, candidate, definitions);
         const conditionExpression = conditionSignature(conditionBlock(modifier));
         unresolved.push(...condition.unresolved);
         referencedProvenance.push(...(condition.helperProvenance ?? []));

package/dist/hoi4_agent_tools/reference/lines.js

@@ -0,0 +1,52 @@
+import { ServiceError } from '../core/result.js';
+/** Preserve source text while bounding one reply by lines and UTF-8 bytes. */
+export function readBoundedLines(lines, firstLine, startLine, startColumn, maxLines, maxBytes) {
+    let lineIndex = startLine - firstLine;
+    let columnIndex = startColumn - 1;
+    if (lineIndex < 0 || lineIndex >= lines.length || columnIndex > (lines[lineIndex]?.length ?? 0)) {
+        throw new ServiceError('REFERENCE_POSITION_OUTSIDE_SECTION', 'Requested position is outside the selected section');
+    }
+    const first = lines[lineIndex];
+    if (columnIndex > 0 &&
+        /[\uD800-\uDBFF]/u.test(first[columnIndex - 1]) &&
+        /[\uDC00-\uDFFF]/u.test(first[columnIndex] ?? '')) {
+        throw new ServiceError('REFERENCE_POSITION_OUTSIDE_SECTION', 'Requested column splits a Unicode character');
+    }
+    const selected = [];
+    let bytes = 0;
+    let endLine = startLine;
+    while (lineIndex < lines.length && selected.length < maxLines) {
+        const line = lines[lineIndex];
+        const remainder = line.slice(columnIndex);
+        const separator = selected.length === 0 ? 0 : 1;
+        const allowance = maxBytes - bytes - separator;
+        if (allowance <= 0)
+            break;
+        let consumed = 0;
+        let used = 0;
+        for (const character of remainder) {
+            const characterBytes = Buffer.byteLength(character, 'utf8');
+            if (used + characterBytes > allowance)
+                break;
+            consumed += character.length;
+            used += characterBytes;
+        }
+        if (consumed === 0 && remainder.length > 0)
+            break;
+        selected.push(remainder.slice(0, consumed));
+        bytes += separator + used;
+        endLine = firstLine + lineIndex;
+        if (consumed < remainder.length) {
+            columnIndex += consumed;
+            break;
+        }
+        lineIndex++;
+        columnIndex = 0;
+    }
+    return {
+        text: selected.join('\n'),
+        endLine,
+        nextLine: lineIndex < lines.length ? firstLine + lineIndex : null,
+        nextColumn: lineIndex < lines.length ? columnIndex + 1 : null,
+    };
+}

package/dist/hoi4_agent_tools/reference/operations.js

@@ -0,0 +1,41 @@
+import { requireOperationScope, resolveOperationWorkspaceId, } from '../core/operation-context.js';
+import { emptyServiceResult } from '../core/result.js';
+import { toolResult } from '../core/operation-result.js';
+import { referenceContextRequestSchema, referenceReadRequestSchema, referenceSearchRequestSchema, sourceLookupRequestSchema, } from '../schemas/reference.js';
+import { ReferenceService } from './service.js';
+import { sourceLookup } from './source-lookup.js';
+const schemas = {
+    'hoi4.reference_search': referenceSearchRequestSchema,
+    'hoi4.reference_read': referenceReadRequestSchema,
+    'hoi4.reference_context': referenceContextRequestSchema,
+    'hoi4.source_lookup': sourceLookupRequestSchema,
+};
+export function isReferenceTool(name) {
+    return Object.hasOwn(schemas, name);
+}
+const sharedReferences = new WeakMap();
+/** One authorization and execution contract for both MCP protocol adapters. */
+export class ReferenceToolService {
+    engine;
+    references;
+    constructor(engine) {
+        this.engine = engine;
+        const cached = sharedReferences.get(engine) ?? new ReferenceService();
+        sharedReferences.set(engine, cached);
+        this.references = cached;
+    }
+    async call(name, input, context, signal) {
+        requireOperationScope(context, 'hoi4:read');
+        const parsed = schemas[name].parse(input);
+        const workspaceId = await resolveOperationWorkspaceId(this.engine, context, parsed.workspaceId, signal);
+        const workspace = this.engine.resolver.get(workspaceId, context.principal);
+        const data = name === 'hoi4.reference_search'
+            ? await this.references.search(workspace, referenceSearchRequestSchema.parse(parsed), signal)
+            : name === 'hoi4.reference_read'
+                ? await this.references.read(workspace, referenceReadRequestSchema.parse(parsed), signal)
+                : name === 'hoi4.reference_context'
+                    ? await this.references.context(workspace, referenceContextRequestSchema.parse(parsed), signal)
+                    : await sourceLookup(this.engine, workspaceId, sourceLookupRequestSchema.parse(parsed), context.principal, signal);
+        return toolResult(emptyServiceResult(workspaceId, data));
+    }
+}

package/dist/hoi4_agent_tools/reference/service.js

@@ -0,0 +1,427 @@
+import { open, realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+import fg from 'fast-glob';
+import { compareCodeUnits, sha256Bytes } from '../core/canonical.js';
+import { ServiceError } from '../core/result.js';
+import { isWithin } from '../core/workspace.js';
+import { readBoundedLines } from './lines.js';
+import { readBoundedFile } from '../core/scanner.js';
+const MAX_FILES = 512;
+const MAX_FILE_BYTES = 2_000_000;
+const MAX_TOTAL_BYTES = 32_000_000;
+const MAX_SECTIONS = 20_000;
+const searchStopWords = new Set([
+    'a',
+    'an',
+    'and',
+    'at',
+    'be',
+    'can',
+    'come',
+    'do',
+    'does',
+    'for',
+    'from',
+    'how',
+    'in',
+    'is',
+    'of',
+    'the',
+    'to',
+    'where',
+    'with',
+    'work',
+]);
+function normalizeTerm(term) {
+    if (term === 'dated')
+        return 'date';
+    if (term.endsWith('ies') && term.length > 5)
+        return `${term.slice(0, -3)}y`;
+    if (term.endsWith('ses') && term.length > 5)
+        return term.slice(0, -2);
+    if (term.endsWith('s') && term.length > 4)
+        return term.slice(0, -1);
+    return term;
+}
+function queryTerms(query) {
+    return [
+        ...new Set((query.toLowerCase().match(/[a-z0-9_.:-]+/gu) ?? [])
+            .map(normalizeTerm)
+            .filter((term) => /[a-z0-9]/u.test(term) && !searchStopWords.has(term))),
+    ];
+}
+function containsTerm(text, term) {
+    if (term.length > 2)
+        return text.includes(term);
+    const escaped = term.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+    return new RegExp(`(^|[^a-z0-9_])${escaped}($|[^a-z0-9_])`, 'u').test(text);
+}
+function snippet(lines, terms = []) {
+    let matching = -1;
+    let best = -1;
+    for (const [index, line] of lines.entries()) {
+        const count = terms.filter((term) => containsTerm(line.toLowerCase(), term)).length;
+        if (count > best) {
+            matching = index;
+            best = count;
+        }
+    }
+    const selected = lines
+        .slice(Math.max(0, matching), Math.max(0, matching) + 3)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .join(' ');
+    return selected.slice(0, 300);
+}
+function sectionize(root, filePath, content, revision) {
+    const lines = content.replace(/^\uFEFF/u, '').split(/\r?\n/u);
+    const relative = path.relative(root.root, filePath).replaceAll('\\', '/');
+    const title = path
+        .basename(filePath)
+        .replace(/\.(md|log)$/u, '')
+        .replaceAll('_', ' ')
+        .replace(/ - Hearts of Iron 4 Wiki$/u, '');
+    const headings = [];
+    let inFence = false;
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (/^\s*(```|~~~)/u.test(line)) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        const match = /^(#{1,6})\s+(.+?)\s*#*\s*$/u.exec(line);
+        if (match)
+            headings.push({ heading: match[2].replace(/<a\b[^>]*><\/a>/gu, '').trim(), start: index });
+        else if (root.kind === 'script_doc' &&
+            filePath.endsWith('.log') &&
+            /^[A-Za-z_][A-Za-z0-9_.:-]*$/u.test(line.trim()) &&
+            !/^\s/u.test(line) &&
+            /^\s+\S/u.test(lines[index + 1] ?? '')) {
+            headings.push({ heading: line.trim(), start: index });
+        }
+    }
+    if (headings.length === 0 || headings[0].start > 0)
+        headings.unshift({ heading: title, start: 0 });
+    return headings.map((current, index) => {
+        const end = headings[index + 1]?.start ?? lines.length;
+        const sectionLines = lines.slice(current.start, end);
+        const id = sha256Bytes(Buffer.from(`${root.kind}\0${relative}\0${current.start + 1}\0${current.heading}`, 'utf8'));
+        return {
+            id,
+            revision,
+            source: root.kind,
+            title,
+            heading: current.heading.slice(0, 512),
+            path: filePath,
+            startLine: current.start + 1,
+            endLine: end,
+            excerpt: snippet(sectionLines),
+            authority: root.authority,
+            lines: sectionLines,
+        };
+    });
+}
+function sourceRoots(workspace) {
+    const gameRoot = workspace.gameRoot ?? (workspace.registration.kind === 'game' ? workspace.modRoot : undefined);
+    return [
+        ...(gameRoot === undefined
+            ? []
+            : [
+                {
+                    kind: 'game_doc',
+                    root: gameRoot,
+                    patterns: ['documentation/**/*.md', 'common/**/*documentation.md'],
+                    authority: 'Installed game documentation',
+                },
+            ]),
+        {
+            kind: 'wiki',
+            root: workspace.wikiRoot ?? path.join(workspace.modRoot, 'paradox_wiki'),
+            patterns: ['**/*.md'],
+            authority: 'Offline Paradox Wiki snapshot',
+        },
+        {
+            kind: 'script_doc',
+            root: workspace.scriptDocsRoot ?? path.join(workspace.modRoot, 'script_docs'),
+            patterns: ['**/*.md', '**/*.log'],
+            authority: 'User-provided game script documentation',
+        },
+    ];
+}
+const surfaceNames = {
+    general: ['Data structures', 'Triggers', 'Effects', 'Modifiers', 'Scopes'],
+    event: [
+        'Event modding',
+        'Data structures',
+        'Effects',
+        'Triggers',
+        'Scopes',
+        'On actions',
+        'Localisation',
+    ],
+    decision: ['Decision modding', 'Effects', 'Triggers', 'Scopes', 'Localisation'],
+    idea: ['Idea modding', 'Modifiers', 'Localisation'],
+    focus: ['National focus modding', 'AI focuses', 'Effects', 'Triggers', 'Localisation'],
+    technology: ['Technology modding', 'Equipment modding', 'Modifiers', 'Localisation'],
+    gui: [
+        'Interface modding',
+        'Scripted GUI modding',
+        'Graphical asset modding',
+        'Localisation',
+        'Scopes',
+    ],
+    map: [
+        'Map modding',
+        'State modding',
+        'Strategic region modding',
+        'Bookmark modding',
+        'Localisation',
+    ],
+    localisation: ['Localisation', 'Data structures'],
+    ai: ['AI modding', 'AI focuses', 'Triggers', 'Scopes'],
+};
+const gameDocNames = {
+    general: ['documentation/script_concept_documentation'],
+    event: [
+        'documentation/effects_documentation',
+        'documentation/triggers_documentation',
+        'common/on_actions/_documentation',
+    ],
+    decision: ['common/decisions/_documentation', 'documentation/effects_documentation'],
+    idea: ['documentation/modifiers_documentation'],
+    focus: [
+        'documentation/effects_documentation',
+        'documentation/triggers_documentation',
+        'common/focus_inlay_windows/documentation',
+    ],
+    technology: ['common/units/equipment/_documentation', 'documentation/modifiers_documentation'],
+    gui: ['common/scripted_guis/_documentation'],
+    map: ['common/map_modes/documentation', 'common/strategic_locations/documentation'],
+    localisation: [
+        'documentation/loc_formatter_documentation',
+        'documentation/loc_objects_documentation',
+    ],
+    ai: ['common/ai_strategy/_documentation', 'documentation/triggers_documentation'],
+};
+/** A workspace-private, read-only reference index over explicitly known local roots. */
+export class ReferenceService {
+    #cache = new Map();
+    #cacheBytes = 0;
+    retain(key, value) {
+        this.#cacheBytes -= this.#cache.get(key)?.bytes ?? 0;
+        this.#cache.delete(key);
+        this.#cache.set(key, value);
+        this.#cacheBytes += value.bytes;
+        while (this.#cacheBytes > MAX_TOTAL_BYTES || this.#cache.size > 1_024) {
+            const oldest = this.#cache.entries().next().value;
+            if (oldest === undefined)
+                break;
+            this.#cache.delete(oldest[0]);
+            this.#cacheBytes -= oldest[1].bytes;
+        }
+    }
+    async inventory(workspace, signal) {
+        const sections = [];
+        const coverage = {
+            game_doc: { files: 0, sections: 0, unavailable: true },
+            wiki: { files: 0, sections: 0, unavailable: true },
+            script_doc: { files: 0, sections: 0, unavailable: true },
+        };
+        let skipped = 0;
+        let bytes = 0;
+        for (const root of sourceRoots(workspace)) {
+            signal?.throwIfAborted();
+            let canonicalRoot;
+            try {
+                canonicalRoot = await realpath(root.root);
+            }
+            catch {
+                coverage[root.kind].unavailable = true;
+                continue;
+            }
+            const configuredAuthorityRoot = root.kind === 'game_doc'
+                ? root.root
+                : root.kind === 'wiki'
+                    ? (workspace.wikiRoot ?? workspace.modRoot)
+                    : (workspace.scriptDocsRoot ?? workspace.modRoot);
+            if (!isWithin(configuredAuthorityRoot, canonicalRoot)) {
+                throw new ServiceError('REFERENCE_ROOT_ESCAPE', 'Reference root resolves outside its configured workspace');
+            }
+            coverage[root.kind].unavailable = false;
+            const names = await fg(root.patterns, {
+                cwd: canonicalRoot,
+                onlyFiles: true,
+                followSymbolicLinks: false,
+                dot: false,
+            });
+            names.sort(compareCodeUnits);
+            for (const name of names) {
+                signal?.throwIfAborted();
+                if (coverage[root.kind].files >= MAX_FILES || sections.length >= MAX_SECTIONS) {
+                    skipped++;
+                    continue;
+                }
+                const candidate = path.join(canonicalRoot, name);
+                const canonical = await realpath(candidate);
+                if (!isWithin(canonicalRoot, canonical)) {
+                    skipped++;
+                    continue;
+                }
+                const metadata = await stat(canonical);
+                if (metadata.size > MAX_FILE_BYTES || bytes + metadata.size > MAX_TOTAL_BYTES) {
+                    skipped++;
+                    continue;
+                }
+                bytes += metadata.size;
+                coverage[root.kind].files++;
+                const key = `${root.kind}:${canonicalRoot}:${canonical}`;
+                const handle = await open(canonical, 'r');
+                let content;
+                try {
+                    const opened = await handle.stat();
+                    const resolvedAfterOpen = await realpath(canonical);
+                    const current = await stat(resolvedAfterOpen);
+                    if (!opened.isFile() ||
+                        !isWithin(canonicalRoot, resolvedAfterOpen) ||
+                        opened.dev !== current.dev ||
+                        opened.ino !== current.ino) {
+                        throw new ServiceError('REFERENCE_SOURCE_CHANGED', 'Reference path changed while opening it; retry the request');
+                    }
+                    content = await readBoundedFile(handle, Math.min(MAX_FILE_BYTES, MAX_TOTAL_BYTES - bytes + metadata.size), signal);
+                }
+                finally {
+                    await handle.close();
+                }
+                bytes += content.length - metadata.size;
+                const revision = sha256Bytes(content);
+                let cached = this.#cache.get(key);
+                if (cached?.revision !== revision) {
+                    cached = {
+                        revision,
+                        bytes: content.length,
+                        sections: sectionize(root, canonical, content.toString('utf8'), revision),
+                    };
+                }
+                this.retain(key, cached);
+                const admitted = cached.sections.slice(0, MAX_SECTIONS - sections.length);
+                if (admitted.length < cached.sections.length)
+                    skipped++;
+                sections.push(...admitted);
+                coverage[root.kind].sections += admitted.length;
+            }
+        }
+        return { sections, coverage, skipped };
+    }
+    async search(workspace, input, signal) {
+        const inventory = await this.inventory(workspace, signal);
+        const matches = this.rank(inventory.sections, input.query, input.sources);
+        return {
+            results: matches.slice(0, input.limit).map(({ section, score, excerpt }) => ({
+                ...this.publicSection(section),
+                score,
+                excerpt,
+            })),
+            total: matches.length,
+            coverage: inventory.coverage,
+            skipped: inventory.skipped,
+        };
+    }
+    rank(sections, question, sources) {
+        const query = question.toLowerCase();
+        const terms = queryTerms(query);
+        return sections
+            .flatMap((section) => {
+            if (sources !== undefined && !sources.includes(section.source))
+                return [];
+            const title = section.title.toLowerCase();
+            const heading = section.heading.toLowerCase();
+            const body = section.lines.join('\n').toLowerCase();
+            let matched = 0;
+            let score = 0;
+            for (const term of terms) {
+                const inTitle = containsTerm(title, term);
+                const inHeading = containsTerm(heading, term);
+                const inBody = containsTerm(body, term);
+                if (!inTitle && !inHeading && !inBody)
+                    continue;
+                matched++;
+                score += (inTitle ? 24 : 0) + (inHeading ? 18 : 0) + (inBody ? 3 : 0);
+            }
+            if (matched < Math.max(1, Math.ceil(terms.length * 0.6)))
+                return [];
+            if (heading === query)
+                score += 100;
+            else if (heading.includes(query))
+                score += 70;
+            if (body.includes(query))
+                score += 30;
+            return [{ section, score, excerpt: snippet(section.lines, terms) }];
+        })
+            .sort((left, right) => right.score - left.score ||
+            compareCodeUnits(left.section.path, right.section.path) ||
+            left.section.startLine - right.section.startLine);
+    }
+    async read(workspace, input, signal) {
+        const inventory = await this.inventory(workspace, signal);
+        const section = inventory.sections.find(({ id }) => id === input.id);
+        if (section === undefined)
+            throw new ServiceError('REFERENCE_SECTION_UNKNOWN', 'Reference section is not in this workspace');
+        if (section.revision !== input.revision)
+            throw new ServiceError('REFERENCE_REVISION_STALE', 'Reference source changed; search again', {
+                currentRevision: section.revision,
+            });
+        const startLine = input.startLine ?? section.startLine;
+        const selected = readBoundedLines(section.lines, section.startLine, startLine, input.startColumn ?? 1, input.maxLines, 8_000);
+        return {
+            ...this.publicSection(section),
+            sectionStartLine: section.startLine,
+            sectionEndLine: section.endLine,
+            startLine,
+            startColumn: input.startColumn ?? 1,
+            ...selected,
+        };
+    }
+    async context(workspace, input, signal) {
+        const inventory = await this.inventory(workspace, signal);
+        const wanted = surfaceNames[input.surface];
+        const selected = [];
+        const missing = [];
+        for (const name of [...new Set(wanted)]) {
+            const section = inventory.sections.find((entry) => entry.source === 'wiki' && entry.title.toLowerCase() === name.toLowerCase());
+            if (section === undefined)
+                missing.push(name);
+            else
+                selected.push(section);
+        }
+        for (const name of gameDocNames[input.surface]) {
+            const section = inventory.sections.find((entry) => entry.source === 'game_doc' &&
+                entry.path.replaceAll('\\', '/').toLowerCase().endsWith(`${name}.md`));
+            if (section !== undefined)
+                selected.push(section);
+            else
+                missing.push(name);
+        }
+        const ranked = input.question === undefined ? [] : this.rank(inventory.sections, input.question).slice(0, 5);
+        const prioritized = [
+            ...ranked.map(({ section }) => section),
+            ...selected.filter((section) => !ranked.some((entry) => entry.section.id === section.id)),
+        ];
+        return {
+            surface: input.surface,
+            sections: prioritized.slice(0, input.limit).map((section) => ({
+                ...this.publicSection(section),
+                excerpt: ranked.find((entry) => entry.section.id === section.id)?.excerpt ?? section.excerpt,
+            })),
+            omitted: Math.max(0, prioritized.length - input.limit),
+            missing,
+            coverage: inventory.coverage,
+            skipped: inventory.skipped,
+        };
+    }
+    publicSection(section) {
+        const { lines: _lines, ...publicSection } = section;
+        return publicSection;
+    }
+}

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

@@ -0,0 +1,90 @@
+import { ServiceError } from '../core/result.js';
+import { decodeSource } from '../core/source/encoding.js';
+import { readBoundedLines } from './lines.js';
+import { scanImpactSemanticReferences } from '../core/impact-semantic.js';
+/** Exact source definitions and usage over the existing shared Clausewitz index. */
+export async function sourceLookup(engine, workspaceId, input, principal, signal) {
+    const snapshot = await engine.scan(workspaceId, {}, principal, signal);
+    if (input.expectedRevision !== undefined && input.expectedRevision !== snapshot.revision) {
+        throw new ServiceError('SOURCE_REVISION_STALE', 'Indexed source changed; look up the symbol again', { currentRevision: snapshot.revision });
+    }
+    const definitions = snapshot.index.symbols
+        .filter((entry) => entry.id === input.symbol && (input.kind === undefined || entry.kind === input.kind))
+        .sort((left, right) => Number(left.overridden) - Number(right.overridden) || right.loadOrder - left.loadOrder)
+        .slice(0, input.maxDefinitions)
+        .map((entry, index) => {
+        const source = snapshot.index.files.get(entry.path);
+        const start = entry.location?.start.line;
+        const end = entry.location?.end.line;
+        const fromLine = index === 0 ? (input.fromLine ?? start) : start;
+        if (fromLine !== undefined &&
+            start !== undefined &&
+            end !== undefined &&
+            (fromLine < start || fromLine > end)) {
+            throw new ServiceError('SOURCE_LINE_OUTSIDE_DEFINITION', 'Requested line is outside a matched definition');
+        }
+        const lines = source === undefined || fromLine === undefined
+            ? []
+            : decodeSource(source.bytes)
+                .text.split(/\r?\n/u)
+                .slice((start ?? fromLine) - 1, end);
+        const selected = fromLine === undefined || lines.length === 0
+            ? null
+            : readBoundedLines(lines, start ?? fromLine, fromLine, index === 0 ? (input.fromColumn ?? 1) : 1, input.maxLines, 2_000);
+        return {
+            kind: entry.kind,
+            id: entry.id,
+            path: entry.path,
+            rootKind: entry.rootKind,
+            loadOrder: entry.loadOrder,
+            overridden: entry.overridden,
+            sourceShadowed: entry.sourceShadowed,
+            startLine: start ?? null,
+            endLine: end ?? null,
+            fromLine: fromLine ?? null,
+            toLine: selected?.endLine ?? null,
+            nextLine: selected?.nextLine ?? null,
+            nextColumn: selected?.nextColumn ?? null,
+            text: selected?.text ?? '',
+        };
+    });
+    const semantic = input.includeReferences
+        ? scanImpactSemanticReferences(snapshot, 200_000, { includeOnActions: true })
+        : undefined;
+    const referenceIdentities = new Set();
+    const matchedReferences = input.includeReferences
+        ? [...snapshot.index.references, ...(semantic?.references ?? [])]
+            .filter((entry) => entry.to === input.symbol && (input.kind === undefined || entry.toKind === input.kind))
+            .filter((entry) => {
+            const key = `${entry.path}:${entry.location?.start.offset ?? 0}:${entry.toKind}:${entry.to}:${entry.kind}`;
+            if (referenceIdentities.has(key))
+                return false;
+            referenceIdentities.add(key);
+            return true;
+        })
+        : [];
+    const references = matchedReferences.slice(0, input.maxReferences).map((entry) => ({
+        kind: entry.kind,
+        from: entry.from,
+        toKind: entry.toKind,
+        path: entry.path,
+        line: entry.location?.start.line ?? null,
+    }));
+    return {
+        revision: snapshot.revision,
+        complete: snapshot.complete,
+        skippedSourceCount: snapshot.skippedSourceCount,
+        definitionCount: snapshot.index.symbols.filter((entry) => entry.id === input.symbol && (input.kind === undefined || entry.kind === input.kind)).length,
+        definitions,
+        references,
+        referencesIncluded: input.includeReferences,
+        referenceCount: matchedReferences.length,
+        referencesTruncated: matchedReferences.length > references.length,
+        referencesComplete: input.includeReferences &&
+            snapshot.complete &&
+            semantic?.complete === true &&
+            semantic.unresolved.length === 0 &&
+            matchedReferences.length <= references.length,
+        unresolvedReferenceCount: semantic?.unresolved.length ?? 0,
+    };
+}

package/dist/hoi4_agent_tools/schemas/analysis.js

@@ -1,5 +1,6 @@
 import { z } from 'zod/v4';
 import { workspaceIdSchema, workspaceRelativePathSchema } from './common.js';
+import { ConditionControlMapSchema } from '../core/condition-schema.js';
 const symbolKindSchema = z.enum([
     'focus_tree',
     'focus',
@@ -111,6 +112,7 @@ export const declaredConditionScenarioSchema = z
     id: z.string().min(1).max(512),
     actor: z.string().max(256).optional(),
     date: z.string().max(64).optional(),
+    controls: ConditionControlMapSchema.optional(),
     state: scenarioStateSchema,
     flags: z.array(z.string().min(1).max(512)).max(10_000).optional(),
     eventTargets: z.record(z.string().max(512), z.string().max(512)).optional(),

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

@@ -8,7 +8,7 @@ import { backgroundRequestKeySchema, workspaceIdSchema, workspaceRelativePathSch
 function compact(schema, description) {
     return z.unknown().describe(description).pipe(schema);
 }
-const compactGuiScenarioSchema = compact(GuiPreviewScenarioSchema, 'GUI preview scenario.');
+const compactGuiScenarioSchema = compact(GuiPreviewScenarioSchema, 'GUI preview scenario; optional date and controls {stateId: controllerTag}.');
 const compactGeneratedScenarioOptionsSchema = compact(GuiGeneratedScenarioOptionsSchema, 'GUI generated-scenario options.');
 const compactGuiHelperSchema = compact(GuiHelperDocumentSchema, 'GUI helper document.');
 export const guiPreviewStateSchema = z.enum([