hoi4-agent-tools 4.0.5 → 4.1.0

package/dist/hoi4_agent_tools/map/derived.js

@@ -136,9 +136,9 @@ function coastPoint(raster, shape, isSea) {
             [0, 1],
             [0, -1],
         ]) {
-            const nx = x + dx;
+            const nx = (x + dx + raster.width) % raster.width;
             const ny = y + dy;
-            if (nx < 0 || ny < 0 || nx >= raster.width || ny >= raster.height)
+            if (ny < 0 || ny >= raster.height)
                 continue;
             const other = raster.provinceIds[ny * raster.width + nx];
             if (other < 0 || !isSea(other))
@@ -154,6 +154,19 @@ function coastPoint(raster, shape, isSea) {
     const middle = points[Math.floor(points.length / 2)];
     return { ...middle, sea };
 }
+/** A sea pixel next to the landing province, staying inside narrow inlets and map edges. */
+function floatingHarborPoint(raster, coast) {
+    for (const distance of [2, 1]) {
+        const x = (coast.x + coast.dx * distance + raster.width) % raster.width;
+        const y = coast.y + coast.dy * distance;
+        if (y < 0 || y >= raster.height)
+            continue;
+        // Keep the same sea association selected from the real coastal contact.
+        if (raster.provinceIds[y * raster.width + x] === coast.sea)
+            return { x, y };
+    }
+    throw new ServiceError('MAP_FLOATING_HARBOR_WATER_UNAVAILABLE', 'The selected coastal contact has no adjacent sea pixel for a floating harbor');
+}
 function rotationFor(dx, dy) {
     // Bitmap y grows downward; map z grows upward.
     return Math.atan2(-dy, dx);
@@ -315,9 +328,8 @@ function planBuildingPositions(index, request) {
                         continue;
                     for (let copy = 0; copy < perOwner && produced < wanted - have; copy += 1, produced += 1) {
                         const floating = slot.name === 'floating_harbor';
-                        // A floating harbour sits on the water two pixels out and names its land province.
-                        const x = floating ? coast.x + coast.dx * 2 : coast.x;
-                        const y = floating ? coast.y + coast.dy * 2 : coast.y;
+                        // Prefer two pixels offshore, with a verified adjacent-water fallback.
+                        const { x, y } = floating ? floatingHarborPoint(raster, coast) : coast;
                         added.push([
                             state.id,
                             slot.name,
@@ -350,7 +362,10 @@ function planBuildingPositions(index, request) {
     }
     return {
         relativePath: document?.file.relativePath ?? `${mapRoot(index)}/buildings.txt`,
-        content: rewriteLines(document, drop, added),
+        // The native building-position reader treats a trailing newline as an empty CSV record.
+        content: Buffer.from(rewriteLines(document, drop, added)
+            .toString('utf8')
+            .replace(/\r?\n$/u, ''), 'utf8'),
     };
 }
 function planUnitPositions(index, request) {

package/dist/hoi4_agent_tools/map/job-operations.js

@@ -4,7 +4,7 @@ import { errorResult, toolResult } from '../core/operation-result.js';
 import { ServiceError } from '../core/result.js';
 import { MAP_VIEW_FIELDS, mapInspectRequestSchema, mapRewriteRequestSchema, } from '../schemas/map-requests.js';
 import { AgentNudger } from './service.js';
-import { inspectMap, completeMapRewrite, normalizeMapInspectRequest, normalizeMapRenderRequest, normalizeMapRewriteRequest, prepareMapRewrite, renderMapView, } from './tool-operations.js';
+import { inspectMap, completeMapRewrite, normalizeMapInspectRequest, normalizeMapRenderRequest, normalizeMapRewriteRequest, prepareMapRewrite, previewMapRewrite, renderMapView, } from './tool-operations.js';
 const wireResult = z.record(z.string(), z.json());
 /** Registers read-only map operations without invoking transport handlers. */
 export function registerMapJobs(operations, engine) {
@@ -54,12 +54,18 @@ export function registerMapJobs(operations, engine) {
             throw new ServiceError('JOB_ARGUMENT_SCOPE_MISMATCH', 'The request workspace does not match the authorized job workspace');
         const release = lifetime.begin();
         try {
-            return await prepareMapRewrite(nudger, normalizeMapRewriteRequest(input), {
+            const operationContext = {
                 workspaceId: context.workspaceId,
                 ...(context.principal === undefined ? {} : { principal: context.principal }),
                 signal: context.signal,
                 progress: (completed, total, message) => context.progress({ completed, total, message }),
-            });
+            };
+            const normalized = normalizeMapRewriteRequest(input);
+            if (normalized.preview)
+                return {
+                    readOnlyPreview: wireResult.parse(JSON.parse(JSON.stringify(toolResult(await previewMapRewrite(nudger, normalized, operationContext))))),
+                };
+            return await prepareMapRewrite(nudger, normalized, operationContext);
         }
         finally {
             release();

package/dist/hoi4_agent_tools/map/operations.js

@@ -9,6 +9,8 @@ import { derivedStateCapital, encodeTextDocument, LEVEL_STATE_BUILDINGS, MapWork
 import { planReferenceRemap, ReferenceRemapError } from './references.js';
 import { generateWorld } from './world.js';
 import { planMapPositions, planSupplyRebuild } from './derived.js';
+import { buildWorldContext } from './world-context.js';
+import { reconcileWorldOutputs } from './world-outputs.js';
 function* cancellationCheckpoint(signal, iteration = 0, stride = 1) {
     if (iteration % stride !== 0)
         return;
@@ -3250,6 +3252,14 @@ export const WORLD_REPLACED_ROOTS = [
     'map/supplyareas',
     'common/bookmarks',
 ];
+const STARTING_SCENARIO_REPLACED_ROOTS = [
+    'common/on_actions',
+    'common/ai_areas',
+    'common/ai_strategy_plans',
+    'common/ai_strategy',
+    'common/decisions',
+    'events',
+];
 /** Add replace_path lines to descriptor.mod, creating a minimal descriptor when none exists. */
 function descriptorWithReplacePaths(index, roots) {
     const existing = index.sourceFiles.find((file) => file.rootKind === 'mod' && normalizeRelative(file.relativePath) === 'descriptor.mod');
@@ -3262,36 +3272,56 @@ function descriptorWithReplacePaths(index, roots) {
     const body = textValue.endsWith('\n') ? textValue : `${textValue}${newline}`;
     return Buffer.from(`${body}${missing.map((root) => `replace_path="${root}"`).join(newline)}${missing.length > 0 ? newline : ''}`, 'utf8');
 }
-function applyCreateWorld(base, changes, operation) {
+function applyCreateWorld(base, changes, operation, context) {
+    const reference = context.referenceWorlds?.get(operation.id);
+    if (operation.reference !== undefined && reference === undefined)
+        throw new ServiceError('MAP_REFERENCE_NOT_PREPARED', 'Reference worlds must be prepared by the authorized workspace service');
     const mapRoot = base.sourceRoots.map[0] ?? 'map';
+    const startingScenario = operation.startingScenario ?? reference !== undefined;
     const world = generateWorld({
-        width: operation.width ?? 1_024,
-        height: operation.height ?? 512,
+        startingScenario,
+        ...(operation.worldName === undefined ? {} : { worldName: operation.worldName }),
+        width: operation.width ?? reference?.surface.width ?? 1_024,
+        height: operation.height ?? reference?.surface.height ?? 512,
         seed: operation.seed ?? 1,
         landCoverage: operation.landCoverage ?? 0.35,
         continents: operation.continents ?? 3,
         ...(operation.landPolygons === undefined ? {} : { landPolygons: operation.landPolygons }),
         landProvincePixels: operation.landProvincePixels ?? 400,
         seaProvincePixels: operation.seaProvincePixels ?? 2_500,
-        provincesPerState: operation.provincesPerState ?? 5,
-        landProvincesPerRegion: operation.landProvincesPerRegion ?? 25,
-        seaProvincesPerRegion: operation.seaProvincesPerRegion ?? 10,
-        countries: operation.countries,
+        provincesPerState: operation.provincesPerState ?? (reference === undefined ? 5 : 12),
+        landProvincesPerRegion: operation.landProvincesPerRegion ?? (reference === undefined ? 25 : 60),
+        seaProvincesPerRegion: operation.seaProvincesPerRegion ?? (reference === undefined ? 10 : 30),
+        countries: operation.countries ??
+            reference?.countries ?? [
+            { tag: 'X01', name: 'Aster' },
+            { tag: 'X02', name: 'Brum' },
+            { tag: 'X03', name: 'Corvel' },
+            { tag: 'X04', name: 'Doran' },
+        ],
+        ...(reference === undefined
+            ? {}
+            : {
+                referenceSurface: reference.surface,
+                referenceCities: reference.cities,
+                referenceLabels: reference.labels,
+            }),
         ...(operation.continentNames === undefined
             ? {}
             : { continentNames: operation.continentNames }),
         startDate: operation.startDate ?? '1936.1.1',
-        rivers: operation.rivers ?? 8,
-    }, {
-        palettes: {},
-        mapRoot,
-        statesRoot: base.sourceRoots.states[0] ?? 'history/states',
-        localisationRoot: base.sourceRoots.localisation[0] ?? 'localisation',
-    });
-    const roots = operation.replaceBaseGame === false ? [] : [...WORLD_REPLACED_ROOTS];
+        rivers: operation.rivers ?? (reference === undefined ? 8 : 80),
+    }, buildWorldContext(base));
+    const roots = operation.replaceBaseGame === false
+        ? []
+        : [...WORLD_REPLACED_ROOTS, ...(startingScenario ? STARTING_SCENARIO_REPLACED_ROOTS : [])];
     replacedRootsByPlan.set(changes, roots);
     for (const file of world.files)
         addChange(changes, file.relativePath, file.content, operation.id, file.mediaType);
+    // Remove only unchanged outputs recorded by a previous generation, before indexing new IDs.
+    for (const file of reconcileWorldOutputs(base.sourceFiles, proposedChanges(changes), operation.id, mapRoot, base.sourceRoots.states, base.sourceRoots.localisation))
+        if (file.content === null)
+            addChange(changes, file.relativePath, null, operation.id, 'text/plain');
     // Start from empty derived files so no base-game position or supply line survives.
     for (const name of [
         'buildings.txt',
@@ -3309,7 +3339,28 @@ function applyCreateWorld(base, changes, operation) {
     const positioned = currentIndex(base, changes);
     for (const file of planSupplyRebuild(positioned, { mode: 'replace' }))
         addChange(changes, file.relativePath, file.content, operation.id, 'text/plain');
+    for (const file of reconcileWorldOutputs(base.sourceFiles, proposedChanges(changes), operation.id, mapRoot, base.sourceRoots.states, base.sourceRoots.localisation))
+        addChange(changes, file.relativePath, file.content, operation.id, file.mediaType ?? 'text/plain');
     return [
+        ...(reference?.diagnostics ?? []).map((message) => ({
+            code: 'MAP_REFERENCE_INTERPRETATION',
+            severity: 'warning',
+            category: 'map',
+            operationId: operation.id,
+            message,
+        })),
+        ...(world.warnings.length === 0
+            ? []
+            : [
+                {
+                    code: 'MAP_WORLD_GENERATION_REVIEW',
+                    severity: 'warning',
+                    category: 'map',
+                    operationId: operation.id,
+                    message: `Drainage generation reported ${world.warnings.length} review notes`,
+                    details: { warningCount: world.warnings.length, samples: world.warnings.slice(0, 5) },
+                },
+            ]),
         {
             code: 'MAP_WORLD_CREATED',
             severity: 'info',
@@ -3405,7 +3456,7 @@ function applyEntityLocator(base, changes, operation) {
     ]);
     addChange(changes, locator.file.relativePath, output, operation.id, 'text/plain');
 }
-function* planMapOperationSteps(base, operations, signal) {
+function* planMapOperationSteps(base, operations, signal, context = {}) {
     yield* cancellationCheckpoint(signal);
     const changes = new Map();
     const diagnostics = [];
@@ -3443,7 +3494,7 @@ function* planMapOperationSteps(base, operations, signal) {
         const boundsCheckpoint = expectedChangedBounds;
         try {
             if (operation.kind === 'create_world')
-                diagnostics.push(...applyCreateWorld(base, changes, operation));
+                diagnostics.push(...applyCreateWorld(base, changes, operation, context));
             else if (operation.kind === 'move_state_provinces')
                 applyMoveStateProvinces(base, changes, operation);
             else if (operation.kind === 'update_state')
@@ -3522,12 +3573,12 @@ function* planMapOperationSteps(base, operations, signal) {
         operations: manifestOperations,
     };
 }
-export function planMapOperations(base, operations, signal) {
-    return completeSynchronously(planMapOperationSteps(base, operations, signal));
+export function planMapOperations(base, operations, signal, context = {}) {
+    return completeSynchronously(planMapOperationSteps(base, operations, signal, context));
 }
 /** Plans map mutations while periodically yielding so protocol cancellation can be delivered. */
-export async function planMapOperationsAsync(base, operations, signal) {
-    return completeCooperatively(planMapOperationSteps(base, operations, signal), signal);
+export async function planMapOperationsAsync(base, operations, signal, context = {}) {
+    return completeCooperatively(planMapOperationSteps(base, operations, signal, context), signal);
 }
 export function mapOperationId(operation) {
     return deterministicId('map_operation', operation);

package/dist/hoi4_agent_tools/map/reference-labels.js

@@ -0,0 +1,238 @@
+/** Offline English OCR for reference artwork. No image paths, URLs, commands or model paths
+ * are accepted from callers. The pinned Tesseract worker protocol is used directly because
+ * its public createWorker promise hides the worker handle until initialization completes;
+ * owning the thread from creation lets us terminate stalled initialization as well as OCR.
+ * The synthetic integration test must pass before changing the pinned OCR dependencies.
+ */
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { Worker } from 'node:worker_threads';
+import sharp from 'sharp';
+import { z } from 'zod';
+import { compareCodeUnits } from '../core/canonical.js';
+import { ServiceError } from '../core/result.js';
+const MAX_BYTES = 32 * 1024 * 1024;
+const MAX_PIXELS = 40_000_000;
+const MAX_OCR_SIDE = 2560;
+const MAX_LABELS = 512;
+const MAX_TSV_BYTES = 2 * 1024 * 1024;
+const OCR_TIMEOUT_MS = 30_000;
+const require = createRequire(import.meta.url);
+let active = false;
+function hasRasterSignature(image) {
+    return (image.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])) ||
+        image.subarray(0, 3).equals(Buffer.from([255, 216, 255])) ||
+        ['GIF87a', 'GIF89a'].includes(image.subarray(0, 6).toString('ascii')) ||
+        (image.subarray(0, 4).toString('ascii') === 'RIFF' &&
+            image.subarray(8, 12).toString('ascii') === 'WEBP') ||
+        image.subarray(0, 4).equals(Buffer.from([73, 73, 42, 0])) ||
+        image.subarray(0, 4).equals(Buffer.from([77, 77, 0, 42])));
+}
+const packetSchema = z.object({
+    jobId: z.string(),
+    status: z.enum(['resolve', 'reject', 'progress']),
+    data: z.unknown(),
+});
+/** Validate and normalize the engine's TSV instead of trusting its untyped nested output. */
+export function parseReferenceLabelTsv(tsv, width, height) {
+    if (Buffer.byteLength(tsv) > MAX_TSV_BYTES ||
+        !Number.isSafeInteger(width) ||
+        !Number.isSafeInteger(height) ||
+        width <= 0 ||
+        height <= 0) {
+        return { labels: [], warnings: ['Reference text output exceeded safe bounds.'] };
+    }
+    const lines = new Map();
+    const uncertainLines = new Set();
+    let rejected = 0;
+    for (const row of tsv.split(/\r?\n/).slice(1)) {
+        if (!row.trim())
+            continue;
+        const fields = row.split('\t');
+        if (fields[0] !== '5')
+            continue;
+        const key = fields.slice(1, 5).join(':');
+        const text = fields.slice(11).join(' ').normalize('NFC').trim();
+        const [left, top, wordWidth, wordHeight, confidence] = fields.slice(6, 11).map(Number);
+        if (fields.length < 12 ||
+            !text ||
+            left === undefined ||
+            top === undefined ||
+            wordWidth === undefined ||
+            wordHeight === undefined ||
+            confidence === undefined ||
+            ![left, top, wordWidth, wordHeight, confidence].every(Number.isFinite) ||
+            left < 0 ||
+            top < 0 ||
+            wordWidth <= 0 ||
+            wordHeight <= 0 ||
+            left + wordWidth > width ||
+            top + wordHeight > height ||
+            confidence < 70 ||
+            confidence > 100 ||
+            !/^[\p{L}\p{M}\d][\p{L}\p{M}\d.,'’()-]*$/u.test(text) ||
+            text.length > 80) {
+            rejected++;
+            uncertainLines.add(key);
+            continue;
+        }
+        const group = lines.get(key) ?? [];
+        group.push({ text, confidence, left, top, width: wordWidth, height: wordHeight });
+        lines.set(key, group);
+    }
+    const labels = [];
+    for (const [key, words] of lines) {
+        // A readable half of an uncertain multiword name is not a reliable place name.
+        if (uncertainLines.has(key))
+            continue;
+        words.sort((a, b) => a.left - b.left || a.top - b.top);
+        const groups = [];
+        for (const word of words) {
+            const group = groups.at(-1);
+            const previous = group?.at(-1);
+            if (!previous ||
+                word.left - (previous.left + previous.width) > 2.5 * Math.max(previous.height, word.height)) {
+                groups.push([word]);
+            }
+            else
+                group.push(word);
+        }
+        for (const group of groups) {
+            const text = group.map((word) => word.text).join(' ');
+            const confidence = group.reduce((sum, word) => sum + word.confidence, 0) / group.length;
+            if (confidence < 80 || text.length < 2 || text.length > 80 || !/[\p{L}]/u.test(text)) {
+                rejected++;
+                continue;
+            }
+            const left = Math.min(...group.map((word) => word.left));
+            const top = Math.min(...group.map((word) => word.top));
+            const right = Math.max(...group.map((word) => word.left + word.width));
+            const bottom = Math.max(...group.map((word) => word.top + word.height));
+            labels.push({
+                text,
+                confidence: Math.round(confidence * 100) / 100,
+                x: (left + right) / (2 * width),
+                y: (top + bottom) / (2 * height),
+                width: (right - left) / width,
+                height: (bottom - top) / height,
+            });
+        }
+    }
+    labels.sort((a, b) => a.y - b.y || a.x - b.x || compareCodeUnits(a.text, b.text));
+    const warnings = [];
+    if (rejected > 0)
+        warnings.push(`${rejected} uncertain or invalid reference text fragment(s) were omitted.`);
+    if (labels.length > MAX_LABELS)
+        warnings.push('Reference text was limited to 512 labels.');
+    if (labels.length === 0)
+        warnings.push('No reliable English labels were readable in the reference image.');
+    return { labels: labels.slice(0, MAX_LABELS), warnings };
+}
+/** One active OCR thread per process; contention is retryable instead of changing generated
+ * names. No queue retains reference image bytes. Worker stdout is never forwarded.
+ */
+export async function extractReferenceLabels(image) {
+    if (!Buffer.isBuffer(image) || image.length === 0 || image.length > MAX_BYTES) {
+        return { labels: [], warnings: ['Reference text image exceeded safe byte bounds.'] };
+    }
+    if (!hasRasterSignature(image)) {
+        return {
+            labels: [],
+            warnings: ['Reference text recognition requires a supported raster image.'],
+        };
+    }
+    if (active)
+        throw new ServiceError('MAP_REFERENCE_OCR_BUSY', 'Offline reference text recognition is busy; retry the request.', { retryable: true });
+    active = true;
+    let worker;
+    let timer;
+    try {
+        const decoded = sharp(image, { limitInputPixels: MAX_PIXELS, animated: false });
+        const metadata = await decoded.metadata();
+        if (!['png', 'jpeg', 'webp', 'tiff', 'gif'].includes(metadata.format) ||
+            !metadata.width ||
+            !metadata.height) {
+            return {
+                labels: [],
+                warnings: ['Reference text recognition requires a supported raster image.'],
+            };
+        }
+        const { data: png, info } = await decoded
+            .flatten({ background: '#ffffff' })
+            .resize(MAX_OCR_SIDE, MAX_OCR_SIDE, { fit: 'inside', withoutEnlargement: true })
+            .png()
+            .toBuffer({ resolveWithObject: true });
+        // Paths resolve only fixed, installed, shrinkwrap-pinned package resources. Missing model
+        // data fails closed; we never let Tesseract choose its default remote language URL.
+        const model = await readFile(require.resolve('@tesseract.js-data/eng/4.0.0_best_int/eng.traineddata.gz'));
+        worker = new Worker(require.resolve('tesseract.js/src/worker-script/node/index.js'), {
+            stdout: true,
+            stderr: true,
+            resourceLimits: { maxOldGenerationSizeMb: 192 },
+            execArgv: [],
+        });
+        // Drain diagnostics without forwarding OCR input, recognized names, paths or stdout.
+        worker.stdout.resume();
+        worker.stderr.resume();
+        const currentWorker = worker;
+        let sequence = 0;
+        let rejectPending;
+        const timeout = new Promise((_resolve, reject) => {
+            timer = setTimeout(() => reject(new ServiceError('MAP_REFERENCE_OCR_TIMEOUT', 'Offline reference text recognition exceeded its time limit; retry the request.', { retryable: true })), OCR_TIMEOUT_MS);
+        });
+        currentWorker.on('error', () => rejectPending?.(new Error('OCR worker failed')));
+        currentWorker.on('exit', () => rejectPending?.(new Error('OCR worker exited')));
+        const send = (action, payload) => {
+            const jobId = `reference-${sequence++}`;
+            return new Promise((resolve, reject) => {
+                rejectPending = reject;
+                const receive = (raw) => {
+                    const packet = packetSchema.safeParse(raw);
+                    if (!packet.success || packet.data.jobId !== jobId || packet.data.status === 'progress')
+                        return;
+                    currentWorker.off('message', receive);
+                    rejectPending = undefined;
+                    if (packet.data.status === 'reject')
+                        reject(new Error('OCR recognition failed'));
+                    else
+                        resolve(packet.data.data);
+                };
+                currentWorker.on('message', receive);
+                currentWorker.postMessage({ workerId: 'reference-labels', jobId, action, payload });
+            });
+        };
+        const recognize = async () => {
+            await send('load', { options: { lstmOnly: true, logging: false } });
+            await send('loadLanguage', {
+                langs: [{ code: 'eng', data: model }],
+                options: { cacheMethod: 'none', gzip: true, lstmOnly: true },
+            });
+            await send('initialize', { langs: 'eng', oem: 1, config: {} });
+            await send('setParameters', {
+                params: { tessedit_pageseg_mode: '11', user_defined_dpi: '300' },
+            });
+            return send('recognize', { image: png, options: {}, output: { text: false, tsv: true } });
+        };
+        const result = await Promise.race([recognize(), timeout]);
+        const output = z.object({ tsv: z.string().max(MAX_TSV_BYTES) }).safeParse(result);
+        if (!output.success)
+            throw new Error('Unsupported OCR output');
+        return parseReferenceLabelTsv(output.data.tsv, info.width, info.height);
+    }
+    catch (error) {
+        if (error instanceof ServiceError)
+            throw error;
+        throw new ServiceError('MAP_REFERENCE_OCR_UNAVAILABLE', 'Offline reference text recognition could not complete; verify the installed OCR dependencies and retry the request.', { retryable: true });
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        try {
+            if (worker)
+                await worker.terminate();
+        }
+        finally {
+            active = false;
+        }
+    }
+}