hoi4-agent-tools 3.0.9 → 3.1.0

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

@@ -0,0 +1,126 @@
+import { z } from 'zod/v4';
+import { ServiceError } from './result.js';
+import { executePlannedTransaction, } from './transaction-execution.js';
+const jsonObject = z.record(z.string(), z.json());
+const defaultCompletion = (execution, reconciled) => Promise.resolve(jsonObject.parse({
+    execution: execution.outcome,
+    reconciled,
+    validationPassed: execution.transaction.validation.passed,
+    artifacts: [
+        ...execution.artifacts,
+        ...(execution.transaction.executionArtifacts ?? []),
+        ...execution.transaction.artifacts,
+    ],
+    changedFiles: execution.outcome === 'applied'
+        ? execution.transaction.files.map(({ relativePath }) => relativePath)
+        : [],
+}));
+/** One shared write boundary for background execution and interrupted-outcome reconciliation. */
+export class JobTransactions {
+    engine;
+    jobs;
+    constructor(engine, jobs) {
+        this.engine = engine;
+        this.jobs = jobs;
+    }
+    async execute(workspaceId, id, ownerToken, transaction, principal, signal, recipe, completion = defaultCompletion) {
+        const job = await this.owned(workspaceId, id, ownerToken, principal, signal);
+        this.assertTransaction(job, transaction);
+        if (job.transaction !== undefined) {
+            if (job.transaction.transactionId !== transaction.transactionId ||
+                job.transaction.planHash !== transaction.planHash)
+                throw new ServiceError('JOB_TRANSACTION_CONFLICT', 'The retry does not match the job transaction binding');
+            return this.reconcile(workspaceId, id, ownerToken, principal, signal, true, completion);
+        }
+        return this.apply(job, ownerToken, transaction, principal, signal, recipe, completion);
+    }
+    async reconcile(workspaceId, id, ownerToken, principal, signal, resumePlanned = true, completion = defaultCompletion) {
+        const job = await this.owned(workspaceId, id, ownerToken, principal, signal);
+        if (job.transaction === undefined)
+            throw new ServiceError('JOB_TRANSACTION_UNBOUND', 'No persisted transaction binding exists for this job');
+        const transaction = await this.engine.transactions.recoverTransaction(workspaceId, job.transaction.transactionId, principal, signal);
+        this.assertTransaction(job, transaction);
+        if (transaction.planHash !== job.transaction.planHash)
+            throw new ServiceError('JOB_TRANSACTION_CONFLICT', 'The recorded transaction plan does not match the job binding');
+        if (transaction.state === 'applied')
+            return this.complete(job, ownerToken, { transaction, outcome: 'applied', artifacts: [] }, true, principal, job.writeRecipe, completion);
+        if (transaction.state === 'planned') {
+            if (resumePlanned)
+                return this.apply(job, ownerToken, transaction, principal, signal, job.writeRecipe, completion);
+            if (job.cancelRequested)
+                return this.jobs.store.updateOwned(this.jobs.scope(workspaceId, principal), id, ownerToken, { status: 'cancelled', cancelRequested: true });
+            return this.fail(job, ownerToken, 'JOB_REWRITE_NOT_APPLIED', 'Execution stopped before source application; the plan was not replayed', principal);
+        }
+        if (transaction.state === 'rolled_back' || transaction.state === 'failed')
+            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 transaction could not establish a completed or restored outcome', principal);
+        throw new ServiceError('JOB_TRANSACTION_UNRESOLVED', 'The transaction has no stable outcome after recovery');
+    }
+    async owned(workspaceId, id, ownerToken, principal, signal) {
+        const job = await this.jobs.get(workspaceId, id, principal, signal);
+        if (job.owner?.token !== ownerToken)
+            throw new ServiceError('JOB_OWNER_CHANGED', 'The job is owned by another execution attempt');
+        if (!job.request.mutation || !['running', 'reconciling'].includes(job.status))
+            throw new ServiceError('JOB_STATE_CONFLICT', 'An active rewrite job is required');
+        return job;
+    }
+    assertTransaction(job, transaction) {
+        if (transaction.workspaceId !== job.scope.workspaceId ||
+            (transaction.principal ?? null) !== job.scope.principal ||
+            transaction.rootFingerprint !== job.scope.rootFingerprint)
+            throw new ServiceError('JOB_TRANSACTION_SCOPE_MISMATCH', 'The transaction does not belong to the authorized job scope');
+    }
+    async apply(job, ownerToken, transaction, principal, signal, recipe, completion = defaultCompletion) {
+        try {
+            const execution = await executePlannedTransaction(this.engine, transaction, principal, signal, {
+                beforeApply: async (planned) => {
+                    const bound = await this.jobs.store.updateOwned(this.jobs.scope(job.scope.workspaceId, principal), job.id, ownerToken, {
+                        transaction: { transactionId: planned.transactionId, planHash: planned.planHash },
+                        ...(recipe === undefined ? {} : { writeRecipe: recipe }),
+                    }, signal);
+                    if (bound.cancelRequested)
+                        throw new DOMException('Job cancellation was requested before application', 'AbortError');
+                },
+            });
+            return await this.complete(job, ownerToken, execution, false, principal, recipe, completion);
+        }
+        catch (error) {
+            // Publication of the job result can fail after the source commit. Consult the journal,
+            // never replay the write merely because the caller did not receive its result.
+            const current = await this.jobs.get(job.scope.workspaceId, job.id, principal);
+            if (current.status === 'completed')
+                return current;
+            if (current.owner?.token !== ownerToken)
+                throw new ServiceError('JOB_OWNER_CHANGED', 'The job is owned by another execution attempt');
+            if (current.transaction !== undefined) {
+                const outcome = await this.engine.transactions.recoverTransaction(job.scope.workspaceId, current.transaction.transactionId, principal);
+                this.assertTransaction(current, outcome);
+                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);
+                if (outcome.state === 'failed')
+                    return this.fail(current, ownerToken, 'JOB_REWRITE_RECOVERY_REQUIRED', 'The transaction could not establish a completed or restored outcome', principal);
+            }
+            if (error.name === 'AbortError') {
+                return this.jobs.store.updateOwned(this.jobs.scope(job.scope.workspaceId, principal), job.id, ownerToken, { status: 'cancelled', cancelRequested: true });
+            }
+            return this.fail(current, ownerToken, error instanceof ServiceError ? error.code : 'JOB_REWRITE_FAILED', error instanceof ServiceError
+                ? error.message
+                : 'The rewrite failed before a committed outcome could be recorded', principal);
+        }
+    }
+    async complete(job, ownerToken, execution, reconciled, principal, recipe, completion = defaultCompletion) {
+        const result = await completion(execution, reconciled, recipe);
+        return this.jobs.store.updateOwned(this.jobs.scope(job.scope.workspaceId, principal), job.id, ownerToken, {
+            status: 'completed',
+            result,
+        });
+    }
+    fail(job, ownerToken, code, message, principal) {
+        return this.jobs.store.updateOwned(this.jobs.scope(job.scope.workspaceId, principal), job.id, ownerToken, { status: 'failed', failure: { code, message } });
+    }
+}

package/dist/hoi4_agent_tools/core/job-worker-host.js

@@ -0,0 +1,200 @@
+import { spawn } from 'node:child_process';
+import { mkdir } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { setTimeout as delay } from 'node:timers/promises';
+import { JobService } from './job-service.js';
+import { jobOwnerLiveness, readCheckpointIdentity } from './job-store.js';
+import { RequestScheduler } from './request-scheduler.js';
+import { SharedRequestCapacity } from './shared-request-capacity.js';
+import { containedGeneratedPath } from './workspace.js';
+import { ServiceError } from './result.js';
+const maximumCheckpointRecoveries = 2;
+const maximumPreDispatchRecoveries = 2;
+/** Bounded, fixed-entry child execution; client cancellation/disconnection never kills a worker. */
+export class JobWorkerHost {
+    engine;
+    jobs;
+    capacity;
+    scheduler;
+    owner = {};
+    constructor(engine, jobs, capacity, scheduler) {
+        this.engine = engine;
+        this.jobs = jobs;
+        this.capacity = capacity;
+        this.scheduler = scheduler;
+    }
+    static async create(engine, jobs) {
+        const state = engine.resolver.serverState();
+        if (state === undefined)
+            throw new ServiceError('JOB_STORAGE_UNAVAILABLE', 'Workers require persistent server state');
+        const root = await containedGeneratedPath(state.root, 'job-workers');
+        await mkdir(root, { recursive: true, mode: 0o700 });
+        const config = engine.resolver.config();
+        return new JobWorkerHost(engine, jobs ?? (await JobService.create(engine.resolver)), new SharedRequestCapacity(root, config.maxSharedTools), new RequestScheduler(config.maxConcurrentTools));
+    }
+    async run(workspaceId, id, principal) {
+        const initial = await this.jobs.get(workspaceId, id, principal);
+        if (['completed', 'cancelled', 'failed'].includes(initial.status))
+            return initial;
+        if (![
+            'hoi4.event_inspect',
+            'hoi4.event_render',
+            'hoi4.event_compare',
+            'hoi4.tech_inspect',
+            'hoi4.tech_render',
+            'hoi4.tech_compare',
+            'hoi4.probability_inspect',
+            'hoi4.probability_evaluate',
+            'hoi4.probability_sweep',
+            'hoi4.probability_simulate',
+            'hoi4.probability_sequence',
+            'hoi4.probability_compare',
+            'hoi4.probability_render',
+            'hoi4.map_inspect',
+            'hoi4.map_render',
+            'hoi4.map_rewrite',
+            'hoi4.gui_inspect',
+            'hoi4.gui_render',
+            'hoi4.gui_rewrite',
+            'hoi4.focus_inspect',
+            'hoi4.focus_render',
+            'hoi4.focus_raster',
+            'hoi4.focus_rewrite',
+        ].includes(initial.request.toolName))
+            throw new ServiceError('JOB_OPERATION_UNAVAILABLE', 'This domain has not yet been registered for worker execution');
+        const signal = new AbortController().signal;
+        const recovered = new Set();
+        let preDispatchRecoveries = 0;
+        for (;;) {
+            try {
+                await this.scheduler.run(this.owner, 1024, signal, () => this.capacity.run(signal, (lease) => this.launch(workspaceId, id, lease, principal)));
+                return await this.jobs.get(workspaceId, id, principal);
+            }
+            catch (error) {
+                const current = await this.jobs.get(workspaceId, id, principal);
+                if (error instanceof ServiceError &&
+                    error.code === 'REQUEST_LEASE_HANDOFF_LOST' &&
+                    (current.status === 'queued' ||
+                        (current.owner !== undefined && jobOwnerLiveness(current.owner) === 'dead')) &&
+                    preDispatchRecoveries < maximumPreDispatchRecoveries) {
+                    // No job request was sent to the child: another bounded admission attempt
+                    // cannot replay a read or a rewrite.
+                    preDispatchRecoveries += 1;
+                    await delay(preDispatchRecoveries * 100);
+                    continue;
+                }
+                const checkpoint = readCheckpointIdentity(current);
+                if (checkpoint !== undefined &&
+                    current.owner !== undefined &&
+                    jobOwnerLiveness(current.owner) === 'dead' &&
+                    recovered.size < maximumCheckpointRecoveries &&
+                    !recovered.has(checkpoint)) {
+                    // A replacement revalidates source identity and checkpoint bytes in the normal
+                    // executor. Never replay writes, repeat a stalled frontier, or reclaim a live owner.
+                    recovered.add(checkpoint);
+                    continue;
+                }
+                return await this.jobs.failInterrupted(workspaceId, id, {
+                    code: error instanceof ServiceError ? error.code : 'JOB_WORKER_FAILED',
+                    message: error instanceof ServiceError
+                        ? error.message
+                        : 'The isolated worker stopped without publishing a result',
+                }, principal);
+            }
+        }
+    }
+    async launch(workspaceId, id, lease, principal) {
+        // Resolve the same configured workspace and grants again immediately before dispatch.
+        await this.jobs.get(workspaceId, id, principal);
+        const sourceMode = import.meta.url.endsWith('.ts');
+        const entry = fileURLToPath(new URL(sourceMode ? './job-worker.ts' : './job-worker.js', import.meta.url));
+        const configuration = this.engine.resolver.config();
+        const registeredWorkspaceIds = new Set(configuration.workspaces.map((workspace) => workspace.id));
+        const resolvedWorkspaces = this.engine.resolver.list();
+        const discoveredWorkspaceIds = resolvedWorkspaces
+            .map((workspace) => workspace.id)
+            .filter((workspaceId) => !registeredWorkspaceIds.has(workspaceId));
+        const preserveDiscoveredGrants = (grant) => grant.allowDiscoveredMods
+            ? {
+                ...grant,
+                workspaceIds: [...new Set([...grant.workspaceIds, ...discoveredWorkspaceIds])],
+            }
+            : grant;
+        const child = spawn(process.execPath, [...(sourceMode ? ['--import', import.meta.resolve('tsx')] : []), entry], {
+            detached: true,
+            cwd: process.cwd(),
+            stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+            windowsHide: true,
+        });
+        const initialized = new Promise((resolve, reject) => {
+            child.once('error', reject);
+            child.once('exit', () => reject(new ServiceError('JOB_WORKER_STARTUP_EXIT', 'The worker exited before completing its readiness handshake')));
+            child.once('message', (value) => {
+                void (async () => {
+                    if (typeof value !== 'object' ||
+                        value === null ||
+                        !('type' in value) ||
+                        value.type !== 'ready' ||
+                        child.pid === undefined)
+                        throw new ServiceError('JOB_WORKER_PROTOCOL', 'The worker did not provide its readiness handshake');
+                    await lease.handoffToProcess(child.pid);
+                    await new Promise((resolve, reject) => {
+                        child.once('disconnect', resolve);
+                        child.send({
+                            configuration: {
+                                ...configuration,
+                                modRoots: [],
+                                workspaces: resolvedWorkspaces.map(({ registration }) => registration),
+                                http: {
+                                    ...configuration.http,
+                                    tokens: configuration.http.tokens.map(preserveDiscoveredGrants),
+                                    principals: configuration.http.principals.map(preserveDiscoveredGrants),
+                                },
+                            },
+                            workspaceId,
+                            jobId: id,
+                            ...(principal === undefined ? {} : { principal }),
+                        }, (error) => {
+                            if (error === null) {
+                                // IPC is startup-only. Closing it after dispatch prevents launcher
+                                // lifetime from becoming an implicit cancellation channel.
+                                if (child.connected)
+                                    child.disconnect();
+                                resolve();
+                            }
+                            else
+                                reject(error);
+                        });
+                    });
+                    resolve();
+                })().catch((error) => {
+                    if (child.connected)
+                        child.disconnect();
+                    reject(error instanceof Error
+                        ? error
+                        : new ServiceError('JOB_WORKER_PROTOCOL', 'Worker initialization failed'));
+                });
+            });
+        });
+        await initialized;
+        for (;;) {
+            const record = await this.jobs.get(workspaceId, id, principal);
+            if (['completed', 'failed', 'cancelled'].includes(record.status))
+                return;
+            if (record.owner !== undefined && record.owner.pid !== child.pid) {
+                if (jobOwnerLiveness(record.owner) === 'alive')
+                    return;
+            }
+            if (child.pid !== undefined) {
+                try {
+                    process.kill(child.pid, 0);
+                }
+                catch (error) {
+                    if (error.code === 'ESRCH')
+                        throw new ServiceError('JOB_WORKER_EXIT', 'The worker stopped without publishing a terminal job outcome');
+                }
+            }
+            await delay(100);
+        }
+    }
+}

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

@@ -0,0 +1,62 @@
+import { z } from 'zod/v4';
+import { serverConfigurationSchema } from './configuration.js';
+import { CoreEngine } from './engine.js';
+import { JobExecutor, JobOperations } from './job-executor.js';
+import { JobService } from './job-service.js';
+import { WorkspaceResolver } from './workspace.js';
+import { registerEventJobs } from '../event/job-operations.js';
+import { registerFocusJobs } from '../focus/job-operations.js';
+import { registerGuiJobs } from '../gui/job-operations.js';
+import { registerMapJobs } from '../map/job-operations.js';
+import { registerProbabilityJobs } from '../probability/job-operations.js';
+import { registerTechnologyJobs } from '../technology/job-operations.js';
+// Fixed internal process entry point. It accepts only a trusted host's structured IPC
+// message, never a script path, module name, callback, command, or transport request.
+const inputSchema = z
+    .object({
+    configuration: serverConfigurationSchema,
+    workspaceId: z.string().min(1),
+    jobId: z.string().regex(/^job_[a-f0-9]{64}$/u),
+    principal: z.string().min(1).optional(),
+})
+    .strict();
+if (process.send === undefined)
+    throw new Error('Job workers require their internal IPC host');
+let started = false;
+const startup = setTimeout(() => {
+    if (!started)
+        process.exit(1);
+}, 30_000);
+startup.unref();
+process.once('disconnect', () => {
+    if (!started)
+        process.exit(0);
+});
+process.once('message', (value) => {
+    started = true;
+    clearTimeout(startup);
+    void (async () => {
+        const input = inputSchema.parse(value);
+        const resolver = await WorkspaceResolver.create(input.configuration);
+        const engine = new CoreEngine(resolver);
+        // Recovery is targeted by the job executor. Do not sweep or interfere with
+        // unrelated live rewrite journals when a worker starts.
+        const jobs = await JobService.create(resolver);
+        const operations = new JobOperations();
+        registerEventJobs(operations, engine);
+        registerTechnologyJobs(operations, engine);
+        registerProbabilityJobs(operations, engine);
+        registerMapJobs(operations, engine);
+        registerGuiJobs(operations, engine);
+        registerFocusJobs(operations, engine);
+        await new JobExecutor(engine, jobs, operations).run(input.workspaceId, input.jobId, input.principal);
+    })()
+        .catch(() => {
+        process.exitCode = 1;
+    })
+        .finally(() => {
+        if (process.connected)
+            process.disconnect();
+    });
+});
+process.send({ type: 'ready' });

package/dist/hoi4_agent_tools/core/operation-context.js

@@ -0,0 +1,31 @@
+import { lstat } from 'node:fs/promises';
+import { ServiceError } from './result.js';
+export async function resolveOperationWorkspaceId(engine, context, workspaceId, signal) {
+    if (workspaceId === 'current' && context.resolveCurrentWorkspaceId !== undefined) {
+        return context.resolveCurrentWorkspaceId(signal);
+    }
+    return engine.resolver.resolveWorkspaceId(workspaceId, context.principal);
+}
+export async function resolveOperationWorkspaceForSource(engine, context, workspaceId, relativePath, signal) {
+    const resolvedWorkspaceId = await resolveOperationWorkspaceId(engine, context, workspaceId, signal);
+    if (workspaceId !== 'current' || relativePath === undefined)
+        return resolvedWorkspaceId;
+    try {
+        const resolved = await engine.resolver.resolvePath(resolvedWorkspaceId, relativePath, 'read', ['mod'], context.principal);
+        signal?.throwIfAborted();
+        if ((await lstat(resolved.path)).isFile())
+            return resolvedWorkspaceId;
+    }
+    catch (error) {
+        if (error.name === 'AbortError')
+            throw error;
+    }
+    return ((await engine.resolver.resolveUniqueModSourceWorkspaceId(relativePath, context.principal, signal)) ?? resolvedWorkspaceId);
+}
+export function requireOperationScope(context, scope) {
+    if (context.scopes !== undefined && !context.scopes.includes(scope)) {
+        throw new ServiceError('AUTH_SCOPE_REQUIRED', `This operation requires the ${scope} scope`, {
+            requiredScope: scope,
+        });
+    }
+}