hoi4-agent-tools 3.10.0 → 4.0.0

package/dist/hoi4_agent_tools/core/domain-scan-patterns.js

@@ -78,6 +78,18 @@ export function countryAssetDiscoveryPatterns(workspace) {
         ...under(roots.gfx, '**/*.gfx'),
     ]);
 }
+/**
+ * The changed files of a map rewrite plus the province definitions they refer to. A state file
+ * lists provinces that `map/definition.csv` defines, usually in the base game, so a scan of the
+ * changed files alone would report every listed province as unresolved.
+ */
+export function mapChangeScanPatterns(relativePaths) {
+    return uniquePatterns([
+        ...exactChangedFilePatterns(relativePaths),
+        'map/default.map',
+        'map/*.csv',
+    ]);
+}
 export function exactChangedFilePatterns(relativePaths) {
     return uniquePatterns(relativePaths.map((relativePath) => relativePath.replaceAll('\\', '/').replace(/^\.\//u, '')));
 }

package/dist/hoi4_agent_tools/core/domain-tools.js

@@ -0,0 +1,65 @@
+import { decisionInspectRequestSchema, impactInspectRequestSchema } from '../schemas/analysis.js';
+import { eventInspectRequestSchema, eventRenderRequestSchema } from '../schemas/event.js';
+import { focusInspectRequestSchema, focusRenderRequestSchema, focusRewriteRequestSchema, } from '../schemas/focus-requests.js';
+import { guiInspectRequestSchema, guiRenderRequestSchema, guiRewriteRequestSchema, } from '../schemas/gui-requests.js';
+import { mapInspectRequestSchema, mapRewriteRequestSchema } from '../schemas/map-requests.js';
+import { probabilityAnalyzeRequestSchema, probabilityInspectRequestSchema, } from '../schemas/probability-requests.js';
+import { mechanicTestRequestSchema, packageCheckRequestSchema, scenarioTestRequestSchema, } from '../schemas/scenarios.js';
+import { technologyInspectRequestSchema, technologyRenderRequestSchema, } from '../schemas/technology.js';
+/**
+ * The single list of domain tools that run as durable jobs. Task routing, worker admission,
+ * request lifecycles and job validation all read this list, so adding, merging or removing a
+ * domain tool happens in one place.
+ */
+export const DOMAIN_TOOL_NAMES = [
+    'hoi4.impact_inspect',
+    'hoi4.decision_inspect',
+    'hoi4.mechanic_test',
+    'hoi4.package_check',
+    'hoi4.scenario_test',
+    'hoi4.event_inspect',
+    'hoi4.event_render',
+    'hoi4.tech_inspect',
+    'hoi4.tech_render',
+    'hoi4.probability_inspect',
+    'hoi4.probability_analyze',
+    'hoi4.map_inspect',
+    'hoi4.map_rewrite',
+    'hoi4.gui_inspect',
+    'hoi4.gui_render',
+    'hoi4.gui_rewrite',
+    'hoi4.focus_inspect',
+    'hoi4.focus_render',
+    'hoi4.focus_rewrite',
+];
+export const DOMAIN_TOOL_ARGUMENT_SCHEMAS = {
+    'hoi4.impact_inspect': impactInspectRequestSchema,
+    'hoi4.decision_inspect': decisionInspectRequestSchema,
+    'hoi4.mechanic_test': mechanicTestRequestSchema,
+    'hoi4.package_check': packageCheckRequestSchema,
+    'hoi4.scenario_test': scenarioTestRequestSchema,
+    'hoi4.event_inspect': eventInspectRequestSchema,
+    'hoi4.event_render': eventRenderRequestSchema,
+    'hoi4.tech_inspect': technologyInspectRequestSchema,
+    'hoi4.tech_render': technologyRenderRequestSchema,
+    'hoi4.probability_inspect': probabilityInspectRequestSchema,
+    'hoi4.probability_analyze': probabilityAnalyzeRequestSchema,
+    'hoi4.map_inspect': mapInspectRequestSchema,
+    'hoi4.map_rewrite': mapRewriteRequestSchema,
+    'hoi4.gui_inspect': guiInspectRequestSchema,
+    'hoi4.gui_render': guiRenderRequestSchema,
+    'hoi4.gui_rewrite': guiRewriteRequestSchema,
+    'hoi4.focus_inspect': focusInspectRequestSchema,
+    'hoi4.focus_render': focusRenderRequestSchema,
+    'hoi4.focus_rewrite': focusRewriteRequestSchema,
+};
+const domainToolNames = new Set(DOMAIN_TOOL_NAMES);
+export function isDomainToolName(name) {
+    return domainToolNames.has(name);
+}
+/** Domain tools that change mod source. */
+export const MUTATION_TOOL_NAMES = new Set([
+    'hoi4.gui_rewrite',
+    'hoi4.map_rewrite',
+    'hoi4.focus_rewrite',
+]);

package/dist/hoi4_agent_tools/core/domain-validation.js

@@ -1,6 +1,6 @@
 import { boundedSourceHashEvidence, publicArtifactLink } from './artifacts.js';
 import { canonicalJson } from './canonical.js';
-import { exactChangedFilePatterns, focusDomainScanPatterns } from './domain-scan-patterns.js';
+import { exactChangedFilePatterns, focusDomainScanPatterns, mapChangeScanPatterns, } from './domain-scan-patterns.js';
 import { parseClausewitz } from './source/index.js';
 import { TRANSACTION_MAX_DIAGNOSTICS } from './transaction-limits.js';
 import { importContinuousFocusPalettes, importFocusTrees, layoutFocusTreeAsync, lintContinuousFocusPalette, lintFocusTree, } from '../focus/index.js';
@@ -31,10 +31,13 @@ export async function postValidateTransaction(engine, transaction, principal, si
     const workspace = engine.resolver.get(transaction.workspaceId, principal);
     const focusTransaction = transaction.operationKind === 'focus-plan-changes' ||
         transaction.operationKind === 'continuous-focus-plan-changes';
+    const changedPaths = transaction.files.map(({ relativePath }) => relativePath);
     const snapshot = await engine.scan(transaction.workspaceId, {
         patterns: focusTransaction
             ? focusDomainScanPatterns(workspace)
-            : exactChangedFilePatterns(transaction.files.map(({ relativePath }) => relativePath)),
+            : transaction.operationKind === 'agent-nudger-map-changes'
+                ? mapChangeScanPatterns(changedPaths)
+                : exactChangedFilePatterns(changedPaths),
     }, principal, signal);
     const changed = new Set(transaction.files.map(({ relativePath }) => sourcePathComparisonKey(relativePath)));
     const diagnostics = snapshot.diagnostics.filter(({ location }) => {

package/dist/hoi4_agent_tools/core/engine.js

@@ -9,6 +9,7 @@ import { TransactionManager, transactionRootFingerprint } from './transactions.j
 import { RequestScheduler } from './request-scheduler.js';
 import { SharedRequestCapacity } from './shared-request-capacity.js';
 import { JobStore } from './job-store.js';
+import { ServiceError } from './result.js';
 /**
  * Completed scans kept per workspace. One tool call often scans several pattern sets (a GUI
  * preview scans layouts, linked definitions and localisation), so a single slot made every
@@ -130,8 +131,21 @@ export class CoreEngine {
     }
     async initialize() {
         for (const workspace of this.resolver.list()) {
-            // Recovery repairs an interrupted internal rewrite before the workspace is exposed.
-            await this.transactions.recover(workspace.id);
+            // Recovery repairs an interrupted internal rewrite before the workspace is exposed. A
+            // journal that cannot be recovered blocks rewrites of its own workspace, not the server.
+            try {
+                await this.transactions.recover(workspace.id);
+            }
+            catch (error) {
+                this.transactions.recordRecoveryFailure(workspace.id, error);
+                process.stderr.write(`${JSON.stringify({
+                    level: 'error',
+                    event: 'transaction_recovery_blocked',
+                    workspaceId: workspace.id,
+                    code: error instanceof ServiceError ? error.code : 'TRANSACTION_RECOVERY_FAILED',
+                    message: error instanceof Error ? error.message : String(error),
+                })}\n`);
+            }
         }
     }
     status(workspaceId, principal) {
@@ -160,6 +174,7 @@ export class CoreEngine {
     }
     async scan(workspaceId, options = {}, principal, signal) {
         signal?.throwIfAborted();
+        await this.resolver.refreshDescriptors(workspaceId, principal);
         const workspace = this.resolver.get(workspaceId, principal);
         const patterns = options.patterns ?? defaultPatterns(workspace);
         const ignore = options.ignore;
@@ -238,6 +253,18 @@ export class CoreEngine {
                         const retained = [...this.#scanCache.keys()].filter((key) => key.startsWith(`${workspaceId}:`));
                         for (const key of retained.slice(0, -SCAN_CACHE_ENTRIES_PER_WORKSPACE))
                             this.#scanCache.delete(key);
+                        // Snapshots hold every file's bytes; keep all of them within twice one scan's limit.
+                        const limit = this.resolver.config().scanMaxBytes * 2;
+                        const bytes = (cached) => cached.files.reduce((sum, { size }) => sum + size, 0);
+                        let retainedBytes = [...this.#scanCache.values()].reduce((sum, cached) => sum + bytes(cached), 0);
+                        for (const [key, cached] of this.#scanCache) {
+                            if (retainedBytes <= limit)
+                                break;
+                            if (key === cacheKey)
+                                continue;
+                            this.#scanCache.delete(key);
+                            retainedBytes -= bytes(cached);
+                        }
                     }
                     return snapshot;
                 });

package/dist/hoi4_agent_tools/core/index.js

@@ -450,7 +450,7 @@ export class SymbolIndex {
         return {
             symbols: this.symbols.slice(...range.symbols),
             references: this.references.slice(...range.references),
-            diagnostics: this.diagnostics.slice(...range.diagnostics),
+            diagnostics: range.diagnostics,
             complete: true,
         };
     }
@@ -466,7 +466,7 @@ export class SymbolIndex {
         const record = () => this.#fileRanges.set(address, {
             symbols: [symbols, this.symbols.length],
             references: [references, this.references.length],
-            diagnostics: [diagnostics, this.diagnostics.length],
+            diagnostics: this.diagnostics.slice(diagnostics),
         });
         const reused = (previous === undefined ? undefined : previous.#segmentAt(address)) ?? cache?.get(address);
         if (reused?.complete === true &&

package/dist/hoi4_agent_tools/core/job-executor.js

@@ -67,7 +67,12 @@ export class JobExecutor {
         this.jobs = jobs;
         this.operations = operations;
     }
-    async run(workspaceId, id, principal) {
+    /**
+     * `deadlineMs` (epoch milliseconds) stops a read-only operation that is still running then
+     * and records JOB_DEADLINE_EXCEEDED as the job's owner. An operation that never yields cannot
+     * observe it; its supervising host stops the process instead.
+     */
+    async run(workspaceId, id, principal, options = {}) {
         const initial = await this.jobs.get(workspaceId, id, principal);
         if (['completed', 'failed', 'cancelled'].includes(initial.status))
             return initial;
@@ -101,6 +106,12 @@ export class JobExecutor {
         const controller = new AbortController();
         const watchStop = new AbortController();
         let watchFailure;
+        const deadlineTimer = options.deadlineMs === undefined || operation.mutation
+            ? undefined
+            : setTimeout(() => {
+                watchFailure = new ServiceError('JOB_DEADLINE_EXCEEDED', 'The job ran past its deadline and was stopped; narrow its selector or limits, or raise jobDeadlineSeconds');
+                controller.abort(watchFailure);
+            }, Math.max(0, options.deadlineMs - Date.now()));
         const watch = (async () => {
             while (!watchStop.signal.aborted) {
                 const current = await this.jobs.get(workspaceId, id, principal);
@@ -183,6 +194,8 @@ export class JobExecutor {
             });
         }
         finally {
+            if (deadlineTimer !== undefined)
+                clearTimeout(deadlineTimer);
             watchStop.abort();
             await watch;
         }

package/dist/hoi4_agent_tools/core/job-operation-registration.js

@@ -1,5 +1,19 @@
 import { JobOperations } from './job-executor.js';
 import { ServiceError } from './result.js';
+const analysisTools = [
+    'hoi4.impact_inspect',
+    'hoi4.decision_inspect',
+    'hoi4.mechanic_test',
+    'hoi4.package_check',
+    'hoi4.scenario_test',
+];
+/** The domain whose registration serves a tool, so a warm worker registers each domain once. */
+export function workerDomain(toolName) {
+    if (analysisTools.includes(toolName))
+        return 'analysis';
+    const match = /^hoi4\.([a-z]+)_/u.exec(toolName);
+    return match?.[1] ?? toolName;
+}
 /** Load one trusted domain after the authenticated job identifies its operation. */
 export async function registerWorkerOperations(engine, toolName) {
     const operations = new JobOperations();
@@ -15,13 +29,7 @@ export async function registerWorkerOperations(engine, toolName) {
         (await import('../probability/job-operations.js')).registerProbabilityJobs(operations, engine);
     else if (toolName.startsWith('hoi4.tech_'))
         (await import('../technology/job-operations.js')).registerTechnologyJobs(operations, engine);
-    else if ([
-        'hoi4.impact_inspect',
-        'hoi4.decision_inspect',
-        'hoi4.mechanic_test',
-        'hoi4.package_check',
-        'hoi4.scenario_test',
-    ].includes(toolName))
+    else if (analysisTools.includes(toolName))
         (await import('./analysis-job-operations.js')).registerAnalysisJobs(operations, engine);
     else
         throw new ServiceError('JOB_OPERATION_UNAVAILABLE', 'No trusted worker domain matches this job');

package/dist/hoi4_agent_tools/core/job-store.js

@@ -251,6 +251,8 @@ export async function publishJobRecord(temporary, target, options = {}) {
     const { publish = rename, ...retry } = options;
     await retryWindowsSharing(() => publish(temporary, target), retry);
 }
+const JOB_STORE_LOCK_WAIT_MS = 120_000;
+const JOB_STORE_LEASE_MAX_AGE_MS = 600_000;
 /** Internal durable job records. Callers must obtain scopes from the authorized workspace resolver. */
 export class JobStore {
     state;
@@ -263,6 +265,22 @@ export class JobStore {
         this.lock = lock;
         this.maxRecordBytes = maxRecordBytes;
     }
+    /**
+     * Run under the store lock, waiting at most JOB_STORE_LOCK_WAIT_MS for it. A lock left by a
+     * crashed process whose pid was reused looks held forever; a bounded wait reports it instead
+     * of hanging every job operation. The wait bound never interrupts the locked action.
+     */
+    async locked(signal, action) {
+        const bounded = AbortSignal.any([signal, AbortSignal.timeout(JOB_STORE_LOCK_WAIT_MS)]);
+        try {
+            return await this.lock.run(bounded, action);
+        }
+        catch (error) {
+            if (bounded.aborted && !signal.aborted)
+                throw new ServiceError('JOB_STORE_BUSY', `The job store lock stayed held for ${JOB_STORE_LOCK_WAIT_MS / 1000} seconds; a crashed server process may still hold it`);
+            throw error;
+        }
+    }
     static async create(state, maxRecordBytes = 4 * 1024 * 1024) {
         if (!Number.isSafeInteger(maxRecordBytes) || maxRecordBytes < 1024)
             throw new RangeError('Job record budget must be an integer of at least 1024 bytes');
@@ -271,7 +289,10 @@ export class JobStore {
         await mkdir(root, { recursive: true, mode: 0o700 });
         await assertUnlinked(path.join(state.root, 'jobs'));
         await containedGeneratedPath(state.root, 'jobs');
-        return new JobStore(state, root, new SharedRequestCapacity(root, 1), maxRecordBytes);
+        return new JobStore(state, root, 
+        // Store operations hold the lock briefly, so an old lease is a crashed holder's even
+        // when its pid now belongs to another process.
+        new SharedRequestCapacity(root, 1, { leaseMaxAgeMs: JOB_STORE_LEASE_MAX_AGE_MS }), maxRecordBytes);
     }
     async submit(scopeInput, requestInput, signal = new AbortController().signal) {
         const scope = scopeSchema.parse(scopeInput);
@@ -287,7 +308,7 @@ export class JobStore {
         const legacyId = request.requestKey === undefined
             ? undefined
             : `job_${hashCanonical({ scope, key: request.requestKey })}`;
-        return this.lock.run(signal, async () => {
+        return this.locked(signal, async () => {
             const current = await this.read(scope, id);
             // Never lose an authenticated retry receipt merely because its identifier predates
             // secret-derived IDs. Read both under the publication lock and fail closed on damage.
@@ -351,7 +372,7 @@ export class JobStore {
     async removeTerminal(scopeInput, idInput, signal = new AbortController().signal) {
         const scope = scopeSchema.parse(scopeInput);
         const id = jobId.parse(idInput);
-        return this.lock.run(signal, async () => {
+        return this.locked(signal, async () => {
             const record = await this.read(scope, id);
             if (record === undefined)
                 return false;
@@ -372,7 +393,7 @@ export class JobStore {
     /** Claim execution once; an interrupted owner must be proven dead, never merely slow. */
     async claim(scope, id, ownerInput, signal = new AbortController().signal) {
         const owner = ownerSchema.parse(ownerInput);
-        return this.lock.run(signal, async () => {
+        return this.locked(signal, async () => {
             const current = await this.get(scope, id, signal);
             if (!['queued', 'running', 'reconciling'].includes(current.status))
                 throw new ServiceError('JOB_TERMINAL', 'The job already has a terminal outcome');
@@ -458,7 +479,7 @@ export class JobStore {
     }
     async update(scope, id, expectedRevision, update, signal = new AbortController().signal) {
         const patch = updateSchema.parse(update);
-        return this.lock.run(signal, async () => {
+        return this.locked(signal, async () => {
             const current = await this.get(scope, id, signal);
             if (current.revision !== expectedRevision)
                 throw new ServiceError('JOB_REVISION_CONFLICT', 'Job state changed; retrieve its current revision before updating');
@@ -490,6 +511,58 @@ export class JobStore {
         });
     }
     /** Operator-internal eviction guard; never returns another principal's job data. */
+    /**
+     * Remove expired, finished read-only records across every scope, inspecting at most
+     * `limit` directory entries. Records are otherwise removed only when they are read again,
+     * so results nobody polls would accumulate without bound.
+     */
+    async sweepExpired(limit = 5_000, signal = new AbortController().signal) {
+        let inspected = 0;
+        let removed = 0;
+        const terminal = (record) => record !== undefined &&
+            !record.request.mutation &&
+            ['completed', 'cancelled', 'failed'].includes(record.status) &&
+            jobRetentionExpired(record);
+        await assertUnlinked(this.root);
+        for await (const directory of await opendir(this.root)) {
+            if (++inspected > limit)
+                break;
+            signal.throwIfAborted();
+            if (directory.name === 'request-capacity' ||
+                directory.isSymbolicLink() ||
+                !directory.isDirectory() ||
+                !digest.safeParse(directory.name).success)
+                continue;
+            const scopeRoot = await containedGeneratedPath(this.root, directory.name);
+            for await (const entry of await opendir(scopeRoot)) {
+                if (++inspected > limit)
+                    break;
+                const id = entry.name.replace(/\.json$/u, '');
+                if (!entry.isFile() || !entry.name.endsWith('.json') || !jobId.safeParse(id).success)
+                    continue;
+                const file = await containedGeneratedPath(scopeRoot, entry.name);
+                const read = () => this.readEnvelope(file, id, directory.name).catch(() => undefined);
+                if (!terminal(await read()))
+                    continue;
+                const deleted = await this.locked(signal, async () => {
+                    if (!terminal(await read()))
+                        return false;
+                    try {
+                        await retryWindowsSharing(() => unlink(file), { signal });
+                        return true;
+                    }
+                    catch (error) {
+                        if (error.code === 'ENOENT')
+                            return false;
+                        throw error;
+                    }
+                });
+                if (deleted)
+                    removed += 1;
+            }
+        }
+        return removed;
+    }
     async checkpointResources(workspace, signal) {
         const resources = new Set();
         let inspected = 0;

package/dist/hoi4_agent_tools/core/job-transactions.js

@@ -55,7 +55,7 @@ export class JobTransactions {
             return this.fail(job, ownerToken, transaction.rollbackStatus === 'applied'
                 ? 'JOB_REWRITE_RESTORED'
                 : 'JOB_REWRITE_RECOVERY_REQUIRED', transaction.rollbackStatus === 'applied'
-                ? 'The interrupted rewrite was restored; it was not replayed'
+                ? `The interrupted rewrite was restored; it was not replayed${failureCause(undefined, transaction)}`
                 : 'The transaction could not establish a completed or restored outcome', principal);
         throw new ServiceError('JOB_TRANSACTION_UNRESOLVED', 'The transaction has no stable outcome after recovery');
     }
@@ -101,7 +101,7 @@ export class JobTransactions {
                 if (outcome.state === 'applied')
                     return this.complete(current, ownerToken, { transaction: outcome, outcome: 'applied', artifacts: [] }, true, principal, current.writeRecipe ?? recipe, completion);
                 if (outcome.state === 'rolled_back')
-                    return this.fail(current, ownerToken, 'JOB_REWRITE_RESTORED', 'The rewrite failed and its original source was restored', principal);
+                    return this.fail(current, ownerToken, 'JOB_REWRITE_RESTORED', `The rewrite failed and its original source was restored${failureCause(error, outcome)}`, principal);
                 if (outcome.state === 'failed')
                     return this.fail(current, ownerToken, 'JOB_REWRITE_RECOVERY_REQUIRED', 'The transaction could not establish a completed or restored outcome', principal);
             }
@@ -124,3 +124,32 @@ export class JobTransactions {
         return this.jobs.store.updateOwned(this.jobs.scope(job.scope.workspaceId, principal), job.id, ownerToken, { status: 'failed', failure: { code, message } });
     }
 }
+/**
+ * Why the write stopped: the error code and message of a service error, else only the error
+ * kind, followed by the first check or diagnostic of the transaction that failed validation.
+ */
+function failureCause(error, transaction) {
+    const recorded = transaction.failure === undefined
+        ? ''
+        : `${transaction.failure.code}: ${transaction.failure.message}`;
+    const cause = error instanceof ServiceError
+        ? `${error.code}: ${error.message}`
+        : error instanceof Error
+            ? error.name
+            : recorded;
+    const failedCheck = transaction.validation.checks.find(({ passed }) => !passed);
+    const blocking = transaction.diagnostics.find(({ severity }) => severity === 'error' || severity === 'blocker');
+    // The blocking diagnostic comes first: it is the part the agent can act on.
+    const text = [
+        blocking === undefined
+            ? ''
+            : `${blocking.code}: ${blocking.message}${blocking.location === undefined
+                ? ''
+                : ` at ${blocking.location.path}:${blocking.location.start.line}`}`,
+        failedCheck?.message ?? '',
+        cause,
+    ]
+        .filter((part) => part !== '')
+        .join('; ');
+    return text === '' ? '' : ` (${text})`.slice(0, 700);
+}