hoi4-agent-tools 3.9.0 → 4.0.0

package/dist/hoi4_agent_tools/core/transactions.js

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import { access, mkdir, open, readFile, readdir, rename, rm, stat, unlink } from 'node:fs/promises';
 import path from 'node:path';
 import { constants } from 'node:fs';
@@ -11,6 +12,17 @@ import { containedGeneratedPath, isWithin, resolvedWorkspaceIdentity } from './w
 import { TRANSACTION_MAX_ARTIFACTS, TRANSACTION_MAX_DIAGNOSTICS, TRANSACTION_MAX_FILES, TRANSACTION_MAX_MANIFEST_BYTES, TRANSACTION_MAX_OPERATIONS, TRANSACTION_MAX_READ_DEPENDENCIES, TRANSACTION_MAX_VALIDATION_CHECKS, } from './transaction-limits.js';
 import { PACKAGE_VERSION, TRANSACTION_VERSION } from '../version.js';
 import { transactionManifestSchema } from '../schemas/transaction.js';
+/**
+ * A file name usable as an artifact name: mod files may contain spaces and other characters
+ * (`history/countries/AUR - Aurelia.txt`) that artifact names do not allow.
+ */
+function diffArtifactStem(relativePath) {
+    const stem = path
+        .basename(relativePath)
+        .replace(/[^A-Za-z0-9._-]+/gu, '_')
+        .replace(/^[^A-Za-z0-9]+/u, '');
+    return (stem.length === 0 ? 'file' : stem).slice(0, 100);
+}
 export function readDependenciesFromScannedFiles(files) {
     const unique = new Map();
     for (const file of files) {
@@ -154,8 +166,32 @@ export class TransactionManager {
         this.maxJournals = maxJournals;
         this.serverState = serverState;
     }
+    /** Workspaces whose startup recovery failed, with the reason; their rewrites are refused. */
+    #recoveryFailures = new Map();
+    /**
+     * Record that startup recovery failed for a workspace. The server still starts and reads the
+     * workspace; rewrites retry recovery and are refused while it keeps failing.
+     */
+    recordRecoveryFailure(workspaceId, error) {
+        this.#recoveryFailures.set(workspaceId, error instanceof Error ? error.message : 'Rewrite journal recovery failed');
+    }
+    async assertRecovered(workspaceId, signal) {
+        if (!this.#recoveryFailures.has(workspaceId))
+            return;
+        try {
+            await this.recover(workspaceId, undefined, signal);
+            this.#recoveryFailures.delete(workspaceId);
+        }
+        catch (error) {
+            if (error.name === 'AbortError')
+                throw error;
+            this.recordRecoveryFailure(workspaceId, error);
+            throw new ServiceError('TRANSACTION_RECOVERY_REQUIRED', `Rewrites of this workspace wait until its interrupted rewrite journal can be recovered: ${this.#recoveryFailures.get(workspaceId)}`);
+        }
+    }
     async plan(input) {
         input.signal?.throwIfAborted();
+        await this.assertRecovered(input.workspaceId, input.signal);
         if (input.changes.length > TRANSACTION_MAX_FILES ||
             input.operations.length > TRANSACTION_MAX_OPERATIONS ||
             (input.readDependencies?.length ?? 0) > TRANSACTION_MAX_READ_DEPENDENCIES ||
@@ -259,7 +295,7 @@ export class TransactionManager {
             };
             if (isText(file.mediaType)) {
                 return {
-                    name: `${path.basename(pending.relativePath)}.diff`,
+                    name: `${diffArtifactStem(pending.relativePath)}.diff`,
                     mimeType: 'text/x-diff',
                     content: unifiedTextDiff(sourceDiffText(pending.before), sourceDiffText(pending.after), `a/${pending.relativePath}`, `b/${pending.relativePath}`, { ...(input.signal === undefined ? {} : { signal: input.signal }) }),
                     provenance: {
@@ -272,7 +308,7 @@ export class TransactionManager {
                 };
             }
             return {
-                name: `${path.basename(pending.relativePath)}.binary-diff.json`,
+                name: `${diffArtifactStem(pending.relativePath)}.binary-diff.json`,
                 mimeType: 'application/json',
                 content: `${canonicalJson(binaryDiff(pending.before ?? Buffer.alloc(0), pending.after ?? Buffer.alloc(0)))}\n`,
                 provenance: {
@@ -336,20 +372,28 @@ export class TransactionManager {
         const workspace = this.resolver.get(workspaceId, options.principal);
         if (!workspace.writeEnabled)
             throw new ServiceError('WRITE_POLICY_DISABLED', 'Workspace writes are not enabled');
-        const manifest = await this.load(workspace, transactionId, {
-            headMode: 'reconcile',
-            ...(options.signal === undefined ? {} : { signal: options.signal }),
-        });
-        this.assertBinding(manifest, workspace, expectedPlanHash, options.principal);
-        if (!manifest.planPayload.validation.passed)
-            throw new ServiceError('TRANSACTION_VALIDATION_BLOCKED', 'Dry-run validation did not pass');
-        if (manifest.files.length === 0)
-            throw new ServiceError('TRANSACTION_NO_CHANGES', 'Transaction contains no file changes');
-        if (manifest.state !== 'planned')
-            throw new ServiceError('TRANSACTION_STATE_INVALID', `Transaction is ${manifest.state}`);
-        if (Date.parse(manifest.expiresAt) <= Date.now())
-            throw new ServiceError('TRANSACTION_EXPIRED', 'Transaction has expired');
+        await this.assertRecovered(workspaceId, options.signal);
+        const loadApplicable = async () => {
+            const loaded = await this.load(workspace, transactionId, {
+                headMode: 'reconcile',
+                ...(options.signal === undefined ? {} : { signal: options.signal }),
+            });
+            this.assertBinding(loaded, workspace, expectedPlanHash, options.principal);
+            if (!loaded.planPayload.validation.passed)
+                throw new ServiceError('TRANSACTION_VALIDATION_BLOCKED', 'Dry-run validation did not pass');
+            if (loaded.files.length === 0)
+                throw new ServiceError('TRANSACTION_NO_CHANGES', 'Transaction contains no file changes');
+            if (loaded.state !== 'planned')
+                throw new ServiceError('TRANSACTION_STATE_INVALID', `Transaction is ${loaded.state}`);
+            if (Date.parse(loaded.expiresAt) <= Date.now())
+                throw new ServiceError('TRANSACTION_EXPIRED', 'Transaction has expired');
+            return loaded;
+        };
+        // Refuse early without the lock, then decide on the journal as it is once the lock is
+        // held: a concurrent apply of the same plan may have finished in between.
+        await loadApplicable();
         return this.withWorkspaceLock(workspace, transactionId, async () => {
+            const manifest = await loadApplicable();
             await this.verifyReadDependencies(workspace, manifest, options.principal, options.signal);
             await this.verifyCurrentFiles(workspace, manifest, 'before', options.principal, options.signal);
             const targets = [];
@@ -379,8 +423,15 @@ export class TransactionManager {
                     if (actualBeforeReplace !== file.beforeSha256) {
                         throw new ServiceError('TRANSACTION_STALE', 'Source changed while transaction output was being staged');
                     }
-                    if (existsBeforeReplace)
+                    if (existsBeforeReplace) {
                         await rename(target.target, target.backup);
+                        // An edit between the hash check and the rename would otherwise be discarded with
+                        // the backup after a successful apply.
+                        if (sha256Bytes(await readFile(target.backup)) !== file.beforeSha256) {
+                            await rename(target.backup, target.target);
+                            throw new ServiceError('TRANSACTION_STALE', 'Source changed while transaction output was being staged');
+                        }
+                    }
                     await options.hooks?.afterBackup?.(file.relativePath, index);
                     if (target.staged !== null) {
                         if (await fileExists(target.target)) {
@@ -597,6 +648,10 @@ export class TransactionManager {
             signal?.throwIfAborted();
             if (!transactionIdPattern.test(entry.name))
                 continue;
+            // A journal folder without a manifest is a plan that never committed: nothing was
+            // applied from it, and pruning removes it once it expires.
+            if (!(await fileExists(path.join(directory, entry.name, 'manifest.json'))))
+                continue;
             const manifest = await this.load(workspace, entry.name, {
                 headMode: 'none',
                 rootBinding: 'ignored',
@@ -656,7 +711,10 @@ export class TransactionManager {
                 }
                 backupValid = true;
             }
-            if (currentHash === file.beforeSha256) {
+            // A file this transaction never replaced keeps whatever it holds now, including an
+            // edit made while the transaction ran; it does not block restoring the others.
+            const untouched = !manifest.appliedFiles.includes(file.relativePath) && !backupExists;
+            if (currentHash === file.beforeSha256 || untouched) {
                 restorations.push({ file, target, backup, staged, mode: 'keep' });
                 continue;
             }
@@ -720,7 +778,7 @@ export class TransactionManager {
             if (await fileExists(restoration.staged))
                 await unlink(restoration.staged);
         }
-        await this.verifyCurrentFiles(workspace, manifest, 'before', principal);
+        await this.verifyCurrentFiles(workspace, manifest, 'before', principal, undefined, new Set(restorations.filter(({ mode }) => mode !== 'keep').map(({ file }) => file.relativePath)));
         manifest.rollbackStatus = 'applied';
     }
     safeFailure(error, fallbackCode, message) {
@@ -739,9 +797,11 @@ export class TransactionManager {
         if ((manifest.principal ?? null) !== (principal ?? null))
             throw new ServiceError('TRANSACTION_PRINCIPAL_MISMATCH', 'Transaction belongs to another principal');
     }
-    async verifyCurrentFiles(workspace, manifest, phase, principal, signal) {
+    async verifyCurrentFiles(workspace, manifest, phase, principal, signal, only) {
         for (const file of manifest.files) {
             signal?.throwIfAborted();
+            if (only !== undefined && !only.has(file.relativePath))
+                continue;
             const { path: target } = await this.resolver.resolvePath(workspace.id, file.relativePath, 'write', ['mod'], principal);
             const exists = await fileExists(target);
             const actual = exists ? sha256Bytes(await readFile(target)) : null;
@@ -1219,7 +1279,13 @@ export class TransactionManager {
             return await action();
         }
         finally {
-            await rm(lock, { recursive: true, force: true });
+            // Release only this holder's lock; never one another process holds after a takeover.
+            const owner = await readFile(path.join(lock, 'owner.json'), 'utf8')
+                .then((text) => JSON.parse(text))
+                .catch(() => undefined);
+            if (owner === undefined ||
+                (owner.instanceId === lockInstanceId && owner.transactionId === transactionId))
+                await rm(lock, { recursive: true, force: true });
         }
     }
     async clearCrashedProcessLock(lock) {
@@ -1243,8 +1309,7 @@ export class TransactionManager {
             catch {
                 return false;
             }
-            await rm(lock, { recursive: true, force: true });
-            return true;
+            return this.retireStaleLock(lock, undefined);
         }
         if (typeof owner !== 'object' ||
             owner === null ||
@@ -1272,7 +1337,33 @@ export class TransactionManager {
             if (error.code !== 'ESRCH')
                 return false;
         }
-        await rm(lock, { recursive: true, force: true });
+        return this.retireStaleLock(lock, canonicalJson(owner));
+    }
+    /**
+     * Move a lock judged stale aside under a unique name; only one process can win the rename.
+     * The moved lock must still carry the owner that was judged stale (`undefined`: no owner
+     * file). Otherwise a new holder took the lock in between, and it is put back untouched.
+     */
+    async retireStaleLock(lock, judgedOwner) {
+        const tombstone = `${lock}.stale-${randomUUID()}`;
+        try {
+            await rename(lock, tombstone);
+        }
+        catch {
+            return false;
+        }
+        let movedOwner;
+        try {
+            movedOwner = canonicalJson(JSON.parse(await readFile(path.join(tombstone, 'owner.json'), 'utf8')));
+        }
+        catch {
+            movedOwner = undefined;
+        }
+        if (movedOwner !== judgedOwner) {
+            await rename(tombstone, lock).catch(() => undefined);
+            return false;
+        }
+        await rm(tombstone, { recursive: true, force: true });
         return true;
     }
 }

package/dist/hoi4_agent_tools/core/workspace.js

@@ -53,6 +53,49 @@ async function discoverDlcLayers(gameRoot) {
         throw new ServiceError('WORKSPACE_DLC_LIMIT', `The game root lists more than ${MAX_DLC_LAYERS} DLC folders`);
     return layers.sort((left, right) => left.id - right.id || compareCodeUnits(left.folder, right.folder));
 }
+/** Read a mod's `descriptor.mod` metadata, or `undefined` when it is absent or unreadable. */
+export async function readModDescriptor(root) {
+    const descriptor = path.join(root, 'descriptor.mod');
+    let bytes;
+    try {
+        const metadata = await lstat(descriptor);
+        if (!metadata.isFile() || metadata.size > MAX_DESCRIPTOR_BYTES)
+            return undefined;
+        bytes = await readFile(descriptor);
+    }
+    catch {
+        return undefined;
+    }
+    const document = parseClausewitz(bytes, descriptor);
+    const result = { tags: [], dependencies: [], replacePaths: [] };
+    const text = (value) => value.slice(0, 256);
+    for (const entry of document.root.entries) {
+        if (entry.type !== 'assignment')
+            continue;
+        const key = entry.key.value.toLowerCase();
+        if (entry.value.type === 'scalar') {
+            const value = text(entry.value.value);
+            if (key === 'name')
+                result.name = value;
+            else if (key === 'version')
+                result.version = value;
+            else if (key === 'supported_version')
+                result.supportedVersion = value;
+            else if (key === 'remote_file_id')
+                result.remoteFileId = value;
+            else if (key === 'replace_path' && result.replacePaths.length < 64)
+                result.replacePaths.push(value);
+            continue;
+        }
+        const list = key === 'tags' ? result.tags : key === 'dependencies' ? result.dependencies : undefined;
+        if (list === undefined)
+            continue;
+        for (const item of entry.value.entries)
+            if (item.type === 'scalar' && list.length < 64)
+                list.push(text(item.value));
+    }
+    return result;
+}
 /**
  * `replace_path` entries from a mod descriptor. The engine unloads earlier-loaded files
  * under each path. Entries that are not safe relative folders are ignored.
@@ -175,12 +218,12 @@ function requestedWorkspaceAlias(value) {
 export function resolvedWorkspaceIdentity(workspace) {
     return hashCanonical({
         id: workspace.id,
-        roots: workspace.roots.map(({ kind, path: rootPath, loadOrder, writable, replacePaths }) => ({
+        roots: workspace.roots.map(({ kind, path: rootPath, loadOrder, writable, replacePaths, identityReplacePaths }) => ({
             kind,
             rootHash: sha256Bytes(process.platform === 'win32' ? rootPath.toLowerCase() : rootPath),
             loadOrder,
             writable,
-            replacePaths,
+            replacePaths: identityReplacePaths ?? replacePaths,
         })),
         behavior: {
             kind: workspace.registration.kind,
@@ -246,6 +289,8 @@ function assertRelative(relativePath) {
 export class WorkspaceResolver {
     configuration;
     #byId = new Map();
+    /** Size and modification time of each descriptor when its `replace_path` entries were read. */
+    #descriptorStamps = new Map();
     #discoveredWorkspaceIds = new Set();
     #storageRoots = [];
     #modRoots = [];
@@ -454,6 +499,34 @@ export class WorkspaceResolver {
             .filter((workspace) => allowed === undefined || allowed.has(workspace.id))
             .sort((a, b) => compareCodeUnits(a.id, b.id));
     }
+    /**
+     * Re-read the `replace_path` entries of the workspace's mod and dependency descriptors when a
+     * descriptor changed since they were last read. A server keeps running while a rewrite such as
+     * a new world adds folders to the descriptor, and later scans must hide the replaced folders.
+     */
+    async refreshDescriptors(workspaceId, principal) {
+        const workspace = this.get(workspaceId, principal);
+        if (workspace.registration.kind === 'game')
+            return;
+        const dependencies = workspace.registration.dependencies;
+        for (const root of workspace.roots) {
+            if (root.kind !== 'mod' && root.kind !== 'dependency')
+                continue;
+            const descriptor = path.join(root.path, 'descriptor.mod');
+            const stamp = await lstat(descriptor).then((metadata) => `${metadata.size}:${metadata.mtimeMs}`, () => 'missing');
+            const key = `${workspace.id}\0${root.path}`;
+            if (this.#descriptorStamps.get(key) === stamp)
+                continue;
+            this.#descriptorStamps.set(key, stamp);
+            const index = workspace.dependencyRoots.indexOf(root.path);
+            const configured = root.kind === 'mod'
+                ? workspace.registration.replacePaths
+                : (dependencies[index]?.replacePaths ?? []);
+            root.replacePaths = [
+                ...new Set([...configured, ...(await descriptorReplacePaths(root.path))]),
+            ];
+        }
+    }
     get(workspaceId, principal) {
         const resolvedWorkspaceId = this.resolveWorkspaceId(workspaceId, principal);
         if (principal !== undefined && !this.allowedWorkspaceIds(principal).has(resolvedWorkspaceId)) {
@@ -476,7 +549,9 @@ export class WorkspaceResolver {
             .split('/')
             .find((segment) => segment !== '.' && segment.length > 0)
             ?.toLowerCase();
-        if (access === 'write' && firstSegment === '.hoi4-agent') {
+        // Server storage holds other principals' proposals and journals; it is never mod source,
+        // for reads as well as writes.
+        if (firstSegment === '.hoi4-agent') {
             throw new ServiceError('PATH_GENERATED_STORAGE_RESERVED', 'Generated .hoi4-agent storage cannot be targeted as mod source');
         }
         const roots = workspace.roots.filter((root) => (rootKinds === undefined || rootKinds.includes(root.kind)) &&
@@ -487,12 +562,12 @@ export class WorkspaceResolver {
                 continue;
             if (access === 'read' && !(await exists(candidate)))
                 continue;
+            if (root.kind === 'mod' &&
+                (pathsOverlap(workspace.artifactRoot, candidate) ||
+                    pathsOverlap(workspace.cacheRoot, candidate))) {
+                throw new ServiceError('PATH_GENERATED_STORAGE_RESERVED', 'Artifact and cache storage cannot be targeted as mod source');
+            }
             if (access === 'write') {
-                if (root.kind === 'mod' &&
-                    (pathsOverlap(workspace.artifactRoot, candidate) ||
-                        pathsOverlap(workspace.cacheRoot, candidate))) {
-                    throw new ServiceError('PATH_GENERATED_STORAGE_RESERVED', 'Artifact and cache storage cannot be targeted as mod source');
-                }
                 const existingParent = await canonicalPath(path.dirname(candidate));
                 if (!isWithin(root.path, existingParent))
                     continue;
@@ -698,6 +773,7 @@ export class WorkspaceResolver {
         ];
         for (const root of roots) {
             root.path = await canonicalPath(root.path);
+            root.identityReplacePaths = root.replacePaths;
         }
         const workspaceBase = {
             id: registration.id,

package/dist/hoi4_agent_tools/decision/ai.js

@@ -85,7 +85,7 @@ export async function inspectDecisionAi(engine, before, id, scenarios, overlay,
             ...(overlay === undefined
                 ? {}
                 : {
-                    proposedUnresolved: 'The proposal changes multiple sources or adds/removes the weighted decision; use probability_compare with explicit source selectors',
+                    proposedUnresolved: 'The proposal changes multiple sources or adds/removes the weighted decision; use hoi4.probability_analyze with analysis compare and explicit source selectors',
                 }),
         };
     }

package/dist/hoi4_agent_tools/decision/service.js

@@ -150,6 +150,34 @@ export class DecisionAnalyzer {
             overrides: inventory.overrides.length,
             scenarios: input.mode === 'inventory' ? 0 : input.scenarios.length,
             unresolvedDefinitions: inventory.unresolvedDefinitions.length,
+            ...(inventory.unresolvedDefinitions.length === 0
+                ? {}
+                : {
+                    unresolvedSample: inventory.unresolvedDefinitions
+                        .slice(0, 8)
+                        .map(({ id, path, reason }) => ({ id, path, reason })),
+                }),
+            // The gate outcome of each scenario answers most inspections without the report.
+            ...(input.mode === 'inspect' && Array.isArray(analysis)
+                ? {
+                    outcomes: analysis.slice(0, 16).map(({ scenarioId, inspection }) => inspection === null
+                        ? { scenarioId, found: false }
+                        : {
+                            scenarioId,
+                            found: true,
+                            eligible: inspection.gates.eligible,
+                            visible: inspection.gates.visible,
+                            available: inspection.gates.available,
+                            ...(inspection.gates.unresolved.length === 0
+                                ? {}
+                                : {
+                                    unresolved: inspection.gates.unresolved
+                                        .slice(0, 5)
+                                        .map(({ code, message }) => ({ code, message: message.slice(0, 300) })),
+                                }),
+                        }),
+                }
+                : {}),
         });
         result.code = complete ? 'DECISION_ANALYZED' : 'DECISION_ANALYZED_PARTIAL';
         result.artifacts = [publicArtifactLink(artifact)];

package/dist/hoi4_agent_tools/decision/source-inventory.js

@@ -137,12 +137,14 @@ export function decisionSourceInventory(snapshot) {
         const category = typeof symbol.metadata.category === 'string' ? symbol.metadata.category : undefined;
         const file = files.get(symbol.path);
         const document = sourceDocument(file, documents);
-        const categoryNode = document === undefined || category === undefined
+        // A file may open the same category block more than once; the decision is in one of them.
+        const decisionNode = document === undefined || category === undefined
             ? undefined
-            : categoryBlock(document, category);
-        const decisionNode = categoryNode === undefined
-            ? undefined
-            : assignments(categoryNode, symbol.id).find((assignment) => assignment.value.type === 'block')?.value;
+            : assignments(document.root, category)
+                .flatMap((categoryAssignment) => categoryAssignment.value.type === 'block'
+                ? assignments(categoryAssignment.value, symbol.id)
+                : [])
+                .find((assignment) => assignment.value.type === 'block')?.value;
         if (file === undefined ||
             document === undefined ||
             category === undefined ||

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

@@ -2,8 +2,8 @@ import { z } from 'zod/v4';
 import { IdleCacheLifetime } from '../core/idle-cache-lifetime.js';
 import { errorResult, toolResult } from '../core/operation-result.js';
 import { ServiceError } from '../core/result.js';
-import { eventInspectRequestSchema, eventRenderRequestSchema, eventCompareRequestSchema, } from '../schemas/event.js';
-import { inspectEvents, renderEvents, compareEvents, normalizeEventInspectionRequest, normalizeEventRenderRequest, normalizeEventCompareRequest, } from './operations.js';
+import { eventInspectRequestSchema, eventRenderRequestSchema } from '../schemas/event.js';
+import { inspectOrCompareEvents, renderEvents, normalizeEventInspectionRequest, normalizeEventRenderRequest, } from './operations.js';
 import { EventChainViewer } from './service.js';
 const wireResult = z.record(z.string(), z.json());
 /** Registers typed event operations without invoking transport handlers. */
@@ -30,7 +30,12 @@ export function registerEventJobs(operations, engine) {
                     'revision' in result.data &&
                     typeof result.data.revision === 'string'
                     ? result.data.revision
-                    : undefined;
+                    : result.data !== null &&
+                        typeof result.data === 'object' &&
+                        'afterRevision' in result.data &&
+                        typeof result.data.afterRevision === 'string'
+                        ? result.data.afterRevision
+                        : undefined;
                 if (revision !== undefined)
                     await context.stageResult(wire, { sourceRevision: revision });
                 return wire;
@@ -45,7 +50,6 @@ export function registerEventJobs(operations, engine) {
             }
         });
     }
-    register('hoi4.event_inspect', eventInspectRequestSchema, normalizeEventInspectionRequest, inspectEvents, 'Analyzing event chain');
+    register('hoi4.event_inspect', eventInspectRequestSchema, normalizeEventInspectionRequest, inspectOrCompareEvents, 'Analyzing event chain');
     register('hoi4.event_render', eventRenderRequestSchema, normalizeEventRenderRequest, renderEvents, 'Rendering event-chain view');
-    register('hoi4.event_compare', eventCompareRequestSchema, normalizeEventCompareRequest, compareEvents, 'Comparing event-chain graphs');
 }

package/dist/hoi4_agent_tools/event/operations.js

@@ -3,13 +3,26 @@ import { helperExpansionValidation } from '../core/helper-expansion.js';
 import { publicArtifactLink } from '../core/artifacts.js';
 import { setInlineFilesScanned } from '../core/operation-result.js';
 import { emptyServiceResult } from '../core/result.js';
-import { eventInspectRequestSchema, eventRenderRequestSchema, eventCompareRequestSchema, } from '../schemas/event.js';
+import { eventInspectRequestSchema, splitEventInspectRequest, eventRenderRequestSchema, eventCompareRequestSchema, } from '../schemas/event.js';
 import { eventDiagnostics, } from './service.js';
 export function normalizeEventInspectionRequest(input) {
     // Validated request fields are JSON-only. Match wire semantics by removing optional
     // undefined fields, including nested source-selector columns, before service dispatch.
     return JSON.parse(JSON.stringify(eventInspectRequestSchema.parse(input)));
 }
+/** Route mode compare to the graph comparison and every other mode to inspection. */
+export function inspectOrCompareEvents(viewer, input) {
+    const split = splitEventInspectRequest(input);
+    if (!split.compare)
+        return inspectEvents(viewer, input);
+    const { signal, principal } = input;
+    return compareEvents(viewer, {
+        ...JSON.parse(JSON.stringify(split.request)),
+        workspaceId: input.workspaceId,
+        ...(principal === undefined ? {} : { principal }),
+        ...(signal === undefined ? {} : { signal }),
+    });
+}
 export function normalizeEventRenderRequest(input) {
     return JSON.parse(JSON.stringify(eventRenderRequestSchema.parse(input)));
 }

package/dist/hoi4_agent_tools/event/service.js

@@ -1308,6 +1308,13 @@ export class EventChainViewer {
         input.signal?.throwIfAborted();
         if (input.proposedSources !== undefined)
             assertProposedSourceBounds(input.proposedSources);
+        // Without references the comparison uses the previous cached revision; with none cached,
+        // say so before scanning the workspace.
+        if (input.before === undefined &&
+            input.after === undefined &&
+            input.proposedSources === undefined &&
+            (this.#state.history.get(input.workspaceId)?.size ?? 0) === 0)
+            throw new ServiceError('EVENT_COMPARISON_BASELINE_REQUIRED', 'Provide a cached revision, graph artifact, or proposed source overlay');
         const refresh = input.refresh ??
             (input.proposedSources !== undefined ||
                 input.before === undefined ||

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

@@ -37,8 +37,7 @@ export function registerFocusJobs(operations, engine) {
         });
     }
     register('hoi4.focus_inspect', focusInspectRequestSchema, normalizeFocusInspectRequest, (input, context) => inspectFocus(engine, workbench, input, context));
-    register('hoi4.focus_render', focusRenderRequestSchema, normalizeFocusRenderRequest, (input, context) => renderFocus(engine, workbench, input, context, false));
-    register('hoi4.focus_raster', focusRenderRequestSchema, normalizeFocusRenderRequest, (input, context) => renderFocus(engine, workbench, input, context, true));
+    register('hoi4.focus_render', focusRenderRequestSchema, normalizeFocusRenderRequest, (input, context) => renderFocus(engine, workbench, input, context, input.png !== false || (input.cropFocusIds?.length ?? 0) > 0));
     operations.registerWrite('hoi4.focus_rewrite', focusRewriteRequestSchema, async (input, context) => {
         if (input.workspaceId !== 'current' && input.workspaceId !== context.workspaceId)
             throw new ServiceError('JOB_ARGUMENT_SCOPE_MISMATCH', 'The request workspace does not match the authorized job workspace');

package/dist/hoi4_agent_tools/focus/tool-operations.js

@@ -583,7 +583,7 @@ export async function inspectFocus(engine, workbench, input, context) {
 export async function renderFocus(engine, workbench, input, context, rasterize) {
     const outputName = rasterize ? 'raster' : 'render';
     if (!rasterize && (input.cropFocusIds?.length ?? 0) > 0)
-        throw new ServiceError('FOCUS_CROP_REQUIRES_RASTER', 'Focus problem crops require focus_raster');
+        throw new ServiceError('FOCUS_CROP_REQUIRES_RASTER', 'Focus problem crops are PNG images; omit png: false');
     await context.progress(0, 4, 'Importing and indexing focus source');
     const workspace = engine.resolver.get(context.workspaceId, context.principal);
     const snapshot = await engine.scan(context.workspaceId, { patterns: focusDomainScanPatterns(workspace) }, context.principal, context.signal);

package/dist/hoi4_agent_tools/gui/scenario-generator.js

@@ -477,24 +477,32 @@ function scriptedImageTokens(scripted) {
  * takes that branch. A token the scenario cannot decide is left out, so it still renders as
  * `[dynamic_loc]`, and caller-supplied values always win.
  */
-export function resolveScenarioScriptedLocalisation(graph, windowName, base, definitions = new ClausewitzEvaluationDefinitions()) {
+export function resolveScenarioScriptedLocalisation(graph, windowName, base, 
+/** Built only when the window shows scripted localisation; building scans every helper. */
+definitions = () => new ClausewitzEvaluationDefinitions()) {
     if (graph.scriptedLocalisation.length === 0)
         return base;
     const scripted = relatedScriptedGuis(graph, windowName);
     const elements = relevantElements(graph, windowName, scripted);
     const textual = tokensIn(sourceTexts(graph, elements, base.language, scripted)).textual;
+    const names = new Set(graph.scriptedLocalisation.map(({ name }) => name));
+    const shown = (token) => names.has(token.slice(token.lastIndexOf('.') + 1));
+    const imageTokens = scriptedImageTokens(scripted);
+    if (![...textual, ...imageTokens].some(shown))
+        return base;
+    const evaluation = definitions();
     const explicitValues = guiExplicitConditionValues(base);
     const values = { ...base.values };
     const templates = new Map();
     const evaluate = (key, kind) => explicitValues[key] !== undefined
         ? undefined
-        : scriptedLocalisationValue(graph, key, base.language, kind, explicitValues, base, definitions, []);
+        : scriptedLocalisationValue(graph, key, base.language, kind, explicitValues, base, evaluation, []);
     for (const key of textual) {
         const template = evaluate(key, 'text');
         if (template !== undefined)
             templates.set(key, template);
     }
-    for (const key of scriptedImageTokens(scripted)) {
+    for (const key of imageTokens) {
         const sprite = evaluate(key, 'image');
         if (sprite !== undefined)
             values[key] = sprite;