hoi4-agent-tools 3.0.9 → 3.2.0

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

@@ -0,0 +1,190 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { z } from 'zod/v4';
+import { currentJobOwner } from './job-store.js';
+import { JobTransactions } from './job-transactions.js';
+import { ServiceError } from './result.js';
+import { PACKAGE_VERSION } from '../version.js';
+import { hashCanonical } from './canonical.js';
+import { jobAnalysisCheckpoints, withAnalysisCheckpoints } from './analysis-checkpoints.js';
+const jsonObject = z.record(z.string(), z.json());
+function defaultWriteResult(execution, reconciled) {
+    const artifacts = [
+        ...execution.artifacts,
+        ...(execution.transaction.executionArtifacts ?? []),
+        ...execution.transaction.artifacts,
+    ];
+    return jsonObject.parse({
+        execution: execution.outcome,
+        reconciled,
+        validationPassed: execution.transaction.validation.passed,
+        artifacts,
+        changedFiles: execution.outcome === 'applied'
+            ? execution.transaction.files.map(({ relativePath }) => relativePath)
+            : [],
+    });
+}
+/** Typed core operations shared by a worker host, never MCP handlers or command strings. */
+export class JobOperations {
+    operations = new Map();
+    registerRead(name, schema, run) {
+        this.add(name, { mutation: false, run: (input, context) => run(schema.parse(input), context) });
+    }
+    registerWrite(name, schema, prepare, complete = (_input, execution, reconciled) => Promise.resolve(defaultWriteResult(execution, reconciled))) {
+        this.add(name, {
+            mutation: true,
+            prepare: async (input, context) => {
+                const prepared = await prepare(schema.parse(input), context);
+                if (!('transaction' in prepared))
+                    return { transaction: prepared };
+                return {
+                    transaction: prepared.transaction,
+                    ...(prepared.recipe === undefined ? {} : { recipe: jsonObject.parse(prepared.recipe) }),
+                };
+            },
+            complete: (input, execution, reconciled, recipe, context) => complete(schema.parse(input), execution, reconciled, recipe, context),
+        });
+    }
+    get(name) {
+        const operation = this.operations.get(name);
+        if (operation === undefined)
+            throw new ServiceError('JOB_OPERATION_UNAVAILABLE', 'No typed core operation is registered for this job');
+        return operation;
+    }
+    add(name, operation) {
+        if (this.operations.has(name))
+            throw new Error(`Duplicate job operation: ${name}`);
+        this.operations.set(name, operation);
+    }
+}
+/** Durable execution coordination; CPU/process isolation is supplied by its worker host. */
+export class JobExecutor {
+    engine;
+    jobs;
+    operations;
+    admissionOwner = {};
+    constructor(engine, jobs, operations) {
+        this.engine = engine;
+        this.jobs = jobs;
+        this.operations = operations;
+    }
+    async run(workspaceId, id, principal) {
+        const initial = await this.jobs.get(workspaceId, id, principal);
+        if (['completed', 'failed', 'cancelled'].includes(initial.status))
+            return initial;
+        const operation = this.operations.get(initial.request.toolName);
+        if (operation.mutation !== initial.request.mutation)
+            throw new ServiceError('JOB_OPERATION_MISMATCH', 'The registered operation does not match the persisted write policy');
+        if (initial.toolVersion !== PACKAGE_VERSION)
+            throw new ServiceError('JOB_VERSION_MISMATCH', 'This job requires its recorded tool version for execution');
+        const scope = this.jobs.scope(workspaceId, principal);
+        const owner = currentJobOwner();
+        let claimed;
+        try {
+            claimed = await this.jobs.store.claim(scope, id, owner);
+        }
+        catch (error) {
+            if (error instanceof ServiceError &&
+                ['JOB_OWNER_ACTIVE', 'JOB_TERMINAL'].includes(error.code))
+                return this.jobs.get(workspaceId, id, principal);
+            throw error;
+        }
+        if (claimed.record.status === 'cancelled')
+            return claimed.record;
+        if (!operation.mutation &&
+            claimed.record.result !== undefined &&
+            claimed.record.checkpoint?.cursor === 'result-ready' &&
+            claimed.record.checkpoint.resultHash === hashCanonical(claimed.record.result))
+            return this.jobs.store.updateOwned(scope, id, owner.token, {
+                status: 'completed',
+                result: claimed.record.result,
+            });
+        const controller = new AbortController();
+        const watchStop = new AbortController();
+        let watchFailure;
+        const watch = (async () => {
+            while (!watchStop.signal.aborted) {
+                const current = await this.jobs.get(workspaceId, id, principal);
+                if (current.cancelRequested) {
+                    controller.abort(new DOMException('Job cancelled', 'AbortError'));
+                    return;
+                }
+                if (current.owner?.token !== owner.token)
+                    throw new ServiceError('JOB_OWNER_CHANGED', 'The execution attempt lost ownership');
+                await delay(250, undefined, { signal: watchStop.signal });
+            }
+        })().catch((error) => {
+            if (watchStop.signal.aborted)
+                return;
+            watchFailure = error;
+            controller.abort(error);
+        });
+        const context = {
+            engine: this.engine,
+            workspaceId,
+            principal,
+            signal: controller.signal,
+            checkpoint: claimed.record.checkpoint,
+            progress: async (progress) => {
+                await this.jobs.store.updateOwned(scope, id, owner.token, { progress }, controller.signal);
+            },
+            saveCheckpoint: async (checkpoint) => {
+                await this.jobs.store.updateOwned(scope, id, owner.token, { checkpoint }, controller.signal);
+            },
+            stageResult: async (result, checkpoint) => {
+                await this.jobs.store.updateOwned(scope, id, owner.token, {
+                    result,
+                    checkpoint: {
+                        ...checkpoint,
+                        cursor: 'result-ready',
+                        resultHash: hashCanonical(result),
+                    },
+                }, controller.signal);
+            },
+        };
+        try {
+            return await this.engine.requests.run(this.admissionOwner, Buffer.byteLength(JSON.stringify(initial.request)), controller.signal, () => this.engine.sharedRequests.run(controller.signal, async () => {
+                if (operation.mutation) {
+                    const writes = new JobTransactions(this.engine, this.jobs);
+                    if (claimed.record.transaction !== undefined)
+                        return writes.reconcile(workspaceId, id, owner.token, principal, undefined, true, (execution, reconciled, recipe) => operation.complete(initial.request.arguments, execution, reconciled, recipe, context));
+                    const prepared = await operation.prepare(initial.request.arguments, context);
+                    return writes.execute(workspaceId, id, owner.token, prepared.transaction, principal, controller.signal, prepared.recipe, (execution, reconciled, recipe) => operation.complete(initial.request.arguments, execution, reconciled, recipe, context));
+                }
+                const result = jsonObject.parse(await withAnalysisCheckpoints(jobAnalysisCheckpoints(context), () => operation.run(initial.request.arguments, context)));
+                controller.signal.throwIfAborted();
+                return this.jobs.store.updateOwned(scope, id, owner.token, {
+                    status: 'completed',
+                    result,
+                });
+            }));
+        }
+        catch (error) {
+            const current = await this.jobs.get(workspaceId, id, principal);
+            if (['completed', 'failed', 'cancelled'].includes(current.status))
+                return current;
+            if (current.owner?.token !== owner.token)
+                throw error;
+            if (operation.mutation && current.transaction !== undefined)
+                return await new JobTransactions(this.engine, this.jobs).reconcile(workspaceId, id, owner.token, principal, undefined, false, (execution, reconciled, recipe) => operation.complete(initial.request.arguments, execution, reconciled, recipe, context));
+            if (current.cancelRequested && watchFailure === undefined)
+                return await this.jobs.store.updateOwned(scope, id, owner.token, {
+                    status: 'cancelled',
+                    cancelRequested: true,
+                });
+            const cause = watchFailure ?? error;
+            return await this.jobs.store.updateOwned(scope, id, owner.token, {
+                status: 'failed',
+                failure: {
+                    code: cause instanceof ServiceError ? cause.code : 'JOB_EXECUTION_FAILED',
+                    message: cause instanceof ServiceError
+                        ? cause.message
+                        : 'The typed operation failed; no completed result was recorded',
+                },
+            });
+        }
+        finally {
+            watchStop.abort();
+            await watch;
+        }
+    }
+}

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

@@ -0,0 +1,112 @@
+import { currentJobOwner, jobRetentionExpired, jobOwnerLiveness, JobStore, } from './job-store.js';
+import { ServiceError } from './result.js';
+import { transactionRootFingerprint } from './transactions.js';
+/** Authorization boundary for persistent jobs; transport inputs never supply an ownership scope. */
+export class JobService {
+    resolver;
+    store;
+    constructor(resolver, store) {
+        this.resolver = resolver;
+        this.store = store;
+    }
+    static async create(resolver) {
+        const state = resolver.serverState();
+        if (state === undefined)
+            throw new ServiceError('JOB_STORAGE_UNAVAILABLE', 'Persistent jobs require operator-owned server state');
+        return new JobService(resolver, await JobStore.create(state));
+    }
+    scope(workspaceId, principal) {
+        const workspace = this.resolver.get(workspaceId, principal);
+        return {
+            workspaceId: workspace.id,
+            workspaceIdentity: workspace.workspaceIdentity,
+            rootFingerprint: transactionRootFingerprint(workspace),
+            principal: principal ?? null,
+        };
+    }
+    async submit(workspaceId, request, principal, signal) {
+        const scope = this.scope(workspaceId, principal);
+        if (request.mutation && !this.resolver.get(workspaceId, principal).writeEnabled)
+            throw new ServiceError('WORKSPACE_WRITE_DISABLED', 'Background rewrites require an enabled workspace write policy');
+        return this.store.submit(scope, request, signal);
+    }
+    async get(workspaceId, id, principal, signal) {
+        const scope = this.scope(workspaceId, principal);
+        const record = await this.store.get(scope, id, signal);
+        if (jobRetentionExpired(record) && !record.request.mutation) {
+            await this.store.removeTerminal(scope, id, signal);
+            throw new ServiceError('JOB_NOT_FOUND', 'The retained job result has expired in the authorized scope');
+        }
+        return record;
+    }
+    async list(workspaceId, principal, options = {}) {
+        const scope = this.scope(workspaceId, principal);
+        const page = await this.store.list(scope, options);
+        const records = [];
+        for (const record of page.records) {
+            if (!jobRetentionExpired(record)) {
+                records.push(record);
+                continue;
+            }
+            if (!record.request.mutation)
+                await this.store.removeTerminal(scope, record.id, options.signal);
+        }
+        return { records, ...(page.next === undefined ? {} : { next: page.next }) };
+    }
+    async cancel(workspaceId, id, principal, signal) {
+        const scope = this.scope(workspaceId, principal);
+        for (;;) {
+            signal?.throwIfAborted();
+            const record = await this.store.get(scope, id, signal);
+            if (['completed', 'failed', 'cancelled'].includes(record.status) || record.cancelRequested)
+                return record;
+            try {
+                return await this.store.update(scope, id, record.revision, {
+                    cancelRequested: true,
+                    ...(record.status === 'queued' ? { status: 'cancelled' } : {}),
+                }, signal);
+            }
+            catch (error) {
+                if (!(error instanceof ServiceError) || error.code !== 'JOB_REVISION_CONFLICT')
+                    throw error;
+            }
+        }
+    }
+    /** Settle a stopped attempt only when no uncertain write outcome can exist. */
+    async failInterrupted(workspaceId, id, failure, principal, signal) {
+        const scope = this.scope(workspaceId, principal);
+        for (;;) {
+            signal?.throwIfAborted();
+            const current = await this.store.get(scope, id, signal);
+            if (['completed', 'failed', 'cancelled'].includes(current.status))
+                return current;
+            if (current.request.mutation && current.transaction !== undefined)
+                throw new ServiceError('JOB_RECONCILIATION_REQUIRED', 'An interrupted rewrite must be reconciled from its bound transaction journal');
+            if (current.status === 'queued') {
+                try {
+                    return await this.store.update(scope, id, current.revision, { status: 'failed', failure }, signal);
+                }
+                catch (error) {
+                    if (!(error instanceof ServiceError) || error.code !== 'JOB_REVISION_CONFLICT')
+                        throw error;
+                    continue;
+                }
+            }
+            if (current.owner === undefined || jobOwnerLiveness(current.owner) !== 'dead')
+                throw new ServiceError('JOB_OWNER_UNRESOLVED', 'The interrupted execution owner has not been proven stopped');
+            const owner = currentJobOwner();
+            try {
+                const claimed = await this.store.claim(scope, id, owner, signal);
+                if (claimed.record.status === 'cancelled')
+                    return claimed.record;
+                return await this.store.updateOwned(scope, id, owner.token, claimed.record.cancelRequested ? { status: 'cancelled' } : { status: 'failed', failure }, signal);
+            }
+            catch (error) {
+                if (error instanceof ServiceError &&
+                    ['JOB_OWNER_ACTIVE', 'JOB_REVISION_CONFLICT'].includes(error.code))
+                    continue;
+                throw error;
+            }
+        }
+    }
+}