hoi4-agent-tools 3.4.0 → 3.5.0

package/dist/hoi4_agent_tools/map/validation.js

@@ -960,6 +960,43 @@ function* validatePositions(index, diagnostics, options) {
         const location = lineLocation(position.document, position.line);
         const state = index.statesById.get(position.stateId);
         const province = index.provinceAtMapCoordinate(position.x, position.z);
+        if (position.building === 'floating_harbor') {
+            const sea = province === undefined ? undefined : index.definitionsById.get(province);
+            const land = index.definitionsById.get(position.adjacentSeaProvince);
+            if (sea?.type !== 'sea') {
+                addDiagnostic(diagnostics, options, {
+                    code: 'MAP_FLOATING_HARBOR_POSITION_REVIEW',
+                    severity: 'warning',
+                    category: 'map',
+                    message: 'Floating-harbor position resolves outside a sea province; review the installed-map precedent',
+                    ...(location === undefined ? {} : { location }),
+                    details: { resolvedProvince: province },
+                });
+            }
+            if (land?.type !== 'land') {
+                addDiagnostic(diagnostics, options, {
+                    code: 'MAP_FLOATING_HARBOR_LAND_INVALID',
+                    severity: 'error',
+                    category: 'map',
+                    message: 'Floating-harbor final field must name an existing land province',
+                    ...(location === undefined ? {} : { location }),
+                    details: { landingProvince: position.adjacentSeaProvince, stateId: position.stateId },
+                });
+            }
+            else if (state === undefined ||
+                !state.provinces.includes(position.adjacentSeaProvince) ||
+                !index.coastalProvinceIds.has(position.adjacentSeaProvince)) {
+                addDiagnostic(diagnostics, options, {
+                    code: 'MAP_FLOATING_HARBOR_ASSOCIATION_REVIEW',
+                    severity: 'warning',
+                    category: 'map',
+                    message: 'Floating-harbor target differs from its state or computed coastal membership',
+                    ...(location === undefined ? {} : { location }),
+                    details: { landingProvince: position.adjacentSeaProvince, stateId: position.stateId },
+                });
+            }
+            continue;
+        }
         if (state === undefined || province === undefined || !state.provinces.includes(province)) {
             addDiagnostic(diagnostics, options, {
                 code: 'MAP_BUILDING_POSITION_INVALID',
@@ -970,7 +1007,7 @@ function* validatePositions(index, diagnostics, options) {
                 details: { resolvedProvince: province },
             });
         }
-        if (position.building === 'naval_base_spawn' || position.building === 'floating_harbor') {
+        if (position.building === 'naval_base_spawn') {
             if (province !== undefined)
                 navalLocatorProvinces.add(province);
             const adjacent = index.definitionsById.get(position.adjacentSeaProvince);

package/dist/hoi4_agent_tools/mcp/server/create-modern-operations.js

@@ -10,6 +10,8 @@ import { MODERN_TASK_ROUTES, ModernTaskRoutingServer } from '../transports/moder
 import { registerModernResources } from '../resources/register-modern.js';
 import { registerModernPrompts } from '../prompts/register-modern.js';
 import { jobControlTools } from '../tools/job.js';
+import { referenceTools } from '../tools/reference.js';
+import { isReferenceTool, ReferenceToolService } from '../../reference/operations.js';
 import { ModernTaskAdapter, TASKS_EXTENSION } from './modern-tasks.js';
 import { SERVER_INSTRUCTIONS } from './instructions.js';
 import { modernProgressReporter, withProgressHeartbeat } from './progress.js';
@@ -39,9 +41,13 @@ function clientCapabilities(envelope) {
 export function createModernOperationServer(engine, context = {}, tasks = new OperationTaskService(engine), options = {}) {
     const adapter = new ModernTaskAdapter(tasks);
     const controls = new JobControlService(engine);
+    const references = new ReferenceToolService(engine);
     const privateOperations = options.createPrivateTools?.(engine, context);
+    const mapEnd = taskToolCatalog.findIndex(({ name }) => name === 'hoi4.map_rewrite') + 1;
     const definitions = [
-        ...taskToolCatalog,
+        ...taskToolCatalog.slice(0, mapEnd),
+        ...referenceTools,
+        ...taskToolCatalog.slice(mapEnd),
         ...jobControlTools,
         ...(privateOperations === undefined
             ? []
@@ -109,6 +115,17 @@ export function createModernOperationServer(engine, context = {}, tasks = new Op
             };
         }
         try {
+            if (isReferenceTool(definition.name)) {
+                const name = definition.name;
+                const result = await withProgressHeartbeat(() => engine.requests.run(references, Buffer.byteLength(JSON.stringify(arguments_)), extra.mcpReq.signal, () => engine.sharedRequests.run(extra.mcpReq.signal, () => references.call(name, arguments_, operationContext, extra.mcpReq.signal))), modernProgressReporter(extra));
+                definition.outputSchema?.parse(result.structuredContent);
+                return CallToolResultSchema.parse({
+                    ...result,
+                    resultType: 'complete',
+                    ttlMs: 0,
+                    cacheScope: 'private',
+                });
+            }
             if (privateOperations !== undefined) {
                 const operations = operationContext === context || options.createPrivateTools === undefined
                     ? privateOperations

package/dist/hoi4_agent_tools/mcp/server/create.js

@@ -4,6 +4,7 @@ import { PACKAGE_NAME, PACKAGE_VERSION } from '../../version.js';
 import { registerFocusTools } from '../tools/focus.js';
 import { registerGuiTools } from '../tools/gui.js';
 import { registerMapTools } from '../tools/map.js';
+import { registerReferenceTools } from '../tools/reference.js';
 import { registerEventTools } from '../tools/event.js';
 import { registerAnalysisTools } from '../tools/analysis.js';
 import { registerTechnologyTools } from '../tools/technology.js';
@@ -53,6 +54,7 @@ export function createMcpServer(engine, context = {}) {
     registerFocusTools(server, engine, serverContext);
     registerGuiTools(server, engine, serverContext);
     registerMapTools(server, engine, serverContext);
+    registerReferenceTools(server, engine, serverContext);
     registerEventTools(server);
     registerAnalysisTools(server);
     registerTechnologyTools(server);

package/dist/hoi4_agent_tools/mcp/server/instructions.js

@@ -1,2 +1,2 @@
 /** Shared agent-facing guidance for both MCP protocol generations. */
-export const SERVER_INSTRUCTIONS = 'Use focus tools for focus trees, GUI tools for interfaces, and map tools for map data. Start unfamiliar event chains with hoi4.event_inspect. Event tools are read-only. Start cross-system source review with hoi4.impact_inspect and decision or mission scenarios with hoi4.decision_inspect. Test declared mechanic steps with hoi4.mechanic_test, package connections with hoi4.package_check, and named suites with hoi4.scenario_test. These analysis tools are read-only. Start technology and doctrine work with hoi4.tech_inspect. Technology tools are read-only. Start weighted AI, MTTH, random, and declared-pool analysis with hoi4.probability_inspect. Probability tools are read-only. Concurrent calls queue automatically and emit periodic progress when the client requests it. Long operations support negotiated MCP tasks; native background rewrites require a stable requestKey. Large evidence is linked as resources.';
+export const SERVER_INSTRUCTIONS = 'Use hoi4.reference_context for local wiki and installed documentation citations, hoi4.reference_search and hoi4.reference_read for exact sections, and hoi4.source_lookup for indexed source examples. Use focus tools for focus trees, GUI tools for interfaces, and map tools for map data. Start unfamiliar event chains with hoi4.event_inspect. Event tools are read-only. Start cross-system source review with hoi4.impact_inspect and decision or mission scenarios with hoi4.decision_inspect. Test declared mechanic steps with hoi4.mechanic_test, package connections with hoi4.package_check, and named suites with hoi4.scenario_test. These analysis tools are read-only. Start technology and doctrine work with hoi4.tech_inspect. Technology tools are read-only. Start weighted AI, MTTH, random, and declared-pool analysis with hoi4.probability_inspect. Probability tools are read-only. Concurrent calls queue automatically and emit periodic progress when the client requests it. Long operations support negotiated MCP tasks; native background rewrites require a stable requestKey. Large evidence is linked as resources.';

package/dist/hoi4_agent_tools/mcp/tools/reference.js

@@ -0,0 +1,60 @@
+import { errorResult, strictOperationResultSchema } from '../../core/operation-result.js';
+import { ReferenceToolService } from '../../reference/operations.js';
+import { referenceContextRequestSchema, referenceReadRequestSchema, referenceSearchRequestSchema, sourceLookupRequestSchema, referenceContextDataSchema, referenceReadDataSchema, referenceSearchDataSchema, sourceLookupDataSchema, } from '../../schemas/reference.js';
+const readOnly = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+};
+export const referenceTools = [
+    {
+        name: 'hoi4.reference_search',
+        title: 'Search local HOI4 references',
+        description: 'Search bounded, cited sections of the configured offline wiki and installed game documentation.',
+        inputSchema: referenceSearchRequestSchema,
+        outputSchema: strictOperationResultSchema(referenceSearchDataSchema),
+        annotations: readOnly,
+    },
+    {
+        name: 'hoi4.reference_read',
+        title: 'Read cited HOI4 reference section',
+        description: 'Read at most 80 lines from one revision-bound local documentation section.',
+        inputSchema: referenceReadRequestSchema,
+        outputSchema: strictOperationResultSchema(referenceReadDataSchema),
+        annotations: readOnly,
+    },
+    {
+        name: 'hoi4.reference_context',
+        title: 'Get HOI4 task references',
+        description: 'Return a compact bundle of offline wiki and installed game documentation citations for a modding surface.',
+        inputSchema: referenceContextRequestSchema,
+        outputSchema: strictOperationResultSchema(referenceContextDataSchema),
+        annotations: readOnly,
+    },
+    {
+        name: 'hoi4.source_lookup',
+        title: 'Look up HOI4 source symbol',
+        description: 'Find exact Clausewitz definitions, override status, a bounded source block, and indexed usages in the configured game and mod.',
+        inputSchema: sourceLookupRequestSchema,
+        outputSchema: strictOperationResultSchema(sourceLookupDataSchema),
+        annotations: readOnly,
+    },
+];
+export function registerReferenceTools(server, engine, context) {
+    const service = new ReferenceToolService(engine);
+    for (const entry of referenceTools) {
+        const { name: _name, ...definition } = entry;
+        const name = entry.name;
+        server.registerTool(name, definition, async (input, extra) => {
+            try {
+                return await service.call(name, input, context, extra.signal);
+            }
+            catch (error) {
+                if (extra.signal.aborted)
+                    throw error;
+                return errorResult(error);
+            }
+        });
+    }
+}

package/dist/hoi4_agent_tools/mechanic/interpreter.js

@@ -13,6 +13,22 @@ const numericEffects = new Map([
     ['add_war_support', { key: 'war_support', mode: 'add', min: 0, max: 1 }],
 ]);
 const harmlessEffects = new Set(['hidden_effect', 'custom_effect_tooltip', 'log', 'tooltip']);
+const variableEffects = new Map([
+    ['set_variable', 'set'],
+    ['set_temp_variable', 'set'],
+    ['add_to_variable', 'add'],
+    ['add_to_temp_variable', 'add'],
+    ['subtract_from_variable', 'subtract'],
+    ['subtract_from_temp_variable', 'subtract'],
+    ['multiply_variable', 'multiply'],
+    ['multiply_temp_variable', 'multiply'],
+    ['divide_variable', 'divide'],
+    ['divide_temp_variable', 'divide'],
+    ['clamp_variable', 'clamp'],
+    ['clamp_temp_variable', 'clamp'],
+    ['round_variable', 'round'],
+    ['round_temp_variable', 'round'],
+]);
 function numeric(value) {
     if (typeof value === 'number' && Number.isFinite(value))
         return value;
@@ -175,6 +191,40 @@ export class MechanicInterpreter {
         return (numeric(scenarioValue(this.state, key, targetScope)) ??
             numeric(scenarioValue(this.state, `variable.${key}`, targetScope)));
     }
+    scopeReference(expression, scope, stack) {
+        const scopeId = (name) => {
+            if (name === 'ROOT')
+                return this.state.scenario.actor ?? 'ROOT';
+            if (name === 'THIS')
+                return scope === 'ROOT'
+                    ? (this.state.scenario.actor ?? 'ROOT')
+                    : this.state.scenario.scopes?.[scope]?.id;
+            if (name === 'PREV') {
+                const previous = stack.findLast((item) => item.startsWith('scope:'))?.slice(6);
+                return previous === undefined
+                    ? undefined
+                    : previous === 'ROOT'
+                        ? (this.state.scenario.actor ?? 'ROOT')
+                        : this.state.scenario.scopes?.[previous]?.id;
+            }
+            return this.state.scenario.scopes?.[name]?.id;
+        };
+        if (expression.startsWith('event_target:'))
+            return this.state.scenario.eventTargets?.[expression.slice(13)];
+        const identifier = /^([A-Za-z0-9_:]+)(?:\.id)?$/u.exec(expression)?.[1];
+        return identifier === undefined ? undefined : scopeId(identifier.toUpperCase());
+    }
+    value(expression, path, scope, stack) {
+        const numberValue = this.number(expression, path, scope);
+        if (numberValue !== undefined)
+            return numberValue;
+        const dotted = /^(ROOT|THIS|FROM|PREV)\.(.+)$/iu.exec(expression);
+        const targetScope = dotted?.[1]?.toUpperCase() === 'THIS' ? scope : (dotted?.[1]?.toUpperCase() ?? scope);
+        const key = dotted?.[2] ?? expression;
+        const existing = scenarioValue(this.state, key, targetScope) ??
+            scenarioValue(this.state, `variable.${key}`, targetScope);
+        return existing ?? this.scopeReference(expression, scope, stack);
+    }
     mathExpression(block, path, scope) {
         const entries = entriesOnly(block);
         if (entries === undefined || entries[0]?.key.value !== 'value')
@@ -410,42 +460,53 @@ export class MechanicInterpreter {
             }
             return;
         }
-        if ([
-            'set_variable',
-            'add_to_variable',
-            'subtract_from_variable',
-            'multiply_variable',
-            'divide_variable',
-            'clamp_variable',
-        ].includes(key)) {
+        const variableMode = variableEffects.get(key);
+        if (variableMode !== undefined) {
+            const variableScope = key.includes('temp_variable') ? 'ROOT' : scope;
+            const scalarVariable = asText(entry.value);
+            if (variableMode === 'round') {
+                const variable = scalarVariable ?? (child === undefined ? undefined : firstScalar(child, 'var')?.value);
+                const before = variable === undefined
+                    ? undefined
+                    : numeric(scenarioValue(this.state, variable, variableScope));
+                const after = before === undefined ? undefined : Math.round(before);
+                if (variable === undefined) {
+                    this.unknown(key, path, scope, 'Variable must resolve');
+                    return;
+                }
+                setScenarioValue(this.state, variable, after, variableScope);
+                this.note(key, path, scope, after === undefined ? 'unresolved' : 'applied', before, after, after === undefined ? 'Variable value is not numeric' : undefined, variable);
+                return;
+            }
             if (child === undefined) {
                 this.unknown(key, path, scope, 'Variable effect requires a block');
                 return;
             }
             const short = assignments(child).find((item) => !['var', 'value', 'min', 'max', 'tooltip'].includes(item.key.value));
             const variable = firstScalar(child, 'var')?.value ?? short?.key.value;
+            if (variable === undefined) {
+                this.unknown(key, path, scope, 'Variable must resolve');
+                return;
+            }
             const expression = firstScalar(child, 'value')?.value ??
                 (short === undefined ? undefined : asText(short.value));
-            if (variable === undefined || expression === undefined) {
-                if (variable === undefined || short?.value.type !== 'block') {
-                    this.unknown(key, path, scope, 'Variable and operand must resolve');
-                    return;
-                }
-            }
-            const value = expression === undefined
-                ? this.mathExpression(short.value, path, scope)
-                : this.number(expression, path, scope);
-            const before = numeric(scenarioValue(this.state, variable, scope)) ?? 0;
-            let after = value;
-            if (value !== undefined && key === 'add_to_variable')
-                after = before + value;
-            if (value !== undefined && key === 'subtract_from_variable')
-                after = before - value;
-            if (value !== undefined && key === 'multiply_variable')
-                after = before * value;
-            if (value !== undefined && key === 'divide_variable')
-                after = value === 0 ? undefined : before / value;
-            if (value !== undefined && key === 'clamp_variable') {
+            const operand = expression === undefined
+                ? variableMode === 'set' && short?.value.type === 'block'
+                    ? this.mathExpression(short.value, path, scope)
+                    : undefined
+                : this.value(expression, path, scope, stack);
+            const previous = scenarioValue(this.state, variable, variableScope);
+            const before = numeric(previous) ?? 0;
+            let after = variableMode === 'set' ? operand : numeric(operand);
+            if (variableMode === 'add' && typeof after === 'number')
+                after = before + after;
+            if (variableMode === 'subtract' && typeof after === 'number')
+                after = before - after;
+            if (variableMode === 'multiply' && typeof after === 'number')
+                after = before * after;
+            if (variableMode === 'divide' && typeof after === 'number')
+                after = after === 0 ? undefined : before / after;
+            if (variableMode === 'clamp') {
                 const minimum = firstScalar(child, 'min')?.value;
                 const maximum = firstScalar(child, 'max')?.value;
                 const min = minimum === undefined ? -Infinity : this.number(minimum, path, scope);
@@ -453,8 +514,8 @@ export class MechanicInterpreter {
                 after =
                     min === undefined || max === undefined ? undefined : Math.max(min, Math.min(max, before));
             }
-            setScenarioValue(this.state, variable, after, scope);
-            this.note(key, path, scope, after === undefined ? 'unresolved' : 'applied', before, after, after === undefined ? 'Numeric operand is unknown or division by zero' : undefined, variable);
+            setScenarioValue(this.state, variable, after, variableScope);
+            this.note(key, path, scope, after === undefined ? 'unresolved' : 'applied', previous, after, after === undefined ? 'Numeric operand is unknown or division by zero' : undefined, variable);
             return;
         }
         if (key === 'set_country_flag' ||

package/dist/hoi4_agent_tools/mechanic/source.js

@@ -77,13 +77,28 @@ export function selectMechanicSource(snapshot, selector) {
 }
 export function scriptedEffectSources(snapshot) {
     const result = new Map();
+    const symbolsByPath = new Map();
     for (const symbol of snapshot.index.symbols) {
         if (symbol.kind !== 'scripted_effect' || symbol.overridden || symbol.sourceShadowed)
             continue;
-        const document = activeDocument(snapshot, symbol.path);
-        const block = document === undefined ? undefined : assignments(document.root, symbol.id)[0]?.value;
-        if (block?.type === 'block')
-            result.set(symbol.id, { id: symbol.id, path: symbol.path, block });
+        const symbols = symbolsByPath.get(symbol.path) ?? [];
+        symbols.push(symbol);
+        symbolsByPath.set(symbol.path, symbols);
+    }
+    for (const [sourcePath, symbols] of symbolsByPath) {
+        const document = activeDocument(snapshot, sourcePath);
+        if (document === undefined)
+            continue;
+        const blocks = new Map();
+        for (const definition of assignments(document.root)) {
+            if (definition.value.type === 'block' && !blocks.has(definition.key.value))
+                blocks.set(definition.key.value, definition.value);
+        }
+        for (const symbol of symbols) {
+            const block = blocks.get(symbol.id);
+            if (block !== undefined)
+                result.set(symbol.id, { id: symbol.id, path: symbol.path, block });
+        }
     }
     return result;
 }

package/dist/hoi4_agent_tools/probability/service.js

@@ -962,7 +962,7 @@ export class ProbabilityAnalyzer {
             adapter !== undefined &&
             adapter !== 'custom_weighted_pool')
             throw new ServiceError('PROBABILITY_ADAPTER_MISMATCH', 'customPoolManifest inspection requires adapter custom_weighted_pool');
-        const snapshot = await this.scan(context, [source?.path], source === undefined ? 'none' : source.inlineClausewitz === undefined ? 'domain' : 'shared');
+        const snapshot = await this.scan(context, [source?.path, source?.snapshotPath], source === undefined ? 'none' : source.inlineClausewitz === undefined ? 'domain' : 'shared');
         if (customPoolManifest !== undefined) {
             const surface = customSurface(customPoolManifest, snapshot.revision);
             const gameVersionVerification = await this.verifyGameVersion(context, 'custom_weighted_pool');
@@ -1150,7 +1150,7 @@ export class ProbabilityAnalyzer {
             request.adapter !== undefined &&
             request.adapter !== 'custom_weighted_pool')
             throw new ServiceError('PROBABILITY_ADAPTER_MISMATCH', 'customPoolManifest requires the custom_weighted_pool adapter');
-        const snapshot = await this.scan(request, [request.source?.path], usingManifest ? 'none' : request.source?.inlineClausewitz === undefined ? 'domain' : 'shared');
+        const snapshot = await this.scan(request, [request.source?.path, request.source?.snapshotPath], usingManifest ? 'none' : request.source?.inlineClausewitz === undefined ? 'domain' : 'shared');
         const resolvedAdapter = usingManifest
             ? 'custom_weighted_pool'
             : resolveSourceBackedAdapter(snapshot, request.source, request.candidatePool ?? [], request.adapter);

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