hoi4-agent-tools 3.2.0 → 3.4.0

package/dist/hoi4_agent_tools/scenario-suite/service.js

@@ -0,0 +1,341 @@
+import { readFile, stat } from 'node:fs/promises';
+import { z } from 'zod/v4';
+import { analysisSourceEvidence } from '../core/analysis-evidence.js';
+import { publicArtifactLink } from '../core/artifacts.js';
+import { canonicalJson, hashCanonical, sha256Bytes } from '../core/canonical.js';
+import { registerAnalysisJobs } from '../core/analysis-job-operations.js';
+import { JobOperations } from '../core/job-executor.js';
+import { setInlineFilesScanned } from '../core/operation-result.js';
+import { emptyServiceResult, ServiceError } from '../core/result.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 { runMechanicCase } from '../mechanic/service.js';
+import { PackageAnalyzer } from '../package-check/service.js';
+import { registerProbabilityJobs } from '../probability/job-operations.js';
+import { scenarioSuiteSchema, } from '../schemas/scenarios.js';
+import { registerTechnologyJobs } from '../technology/job-operations.js';
+import { PACKAGE_VERSION } from '../version.js';
+const MAX_SUITE_BYTES = 8 * 1024 * 1024;
+const continuationSchema = z
+    .object({
+    version: z.literal(1),
+    workspaceIdentity: z.string().regex(/^[a-f0-9]{64}$/u),
+    principal: z.string(),
+    suiteHash: z.string().regex(/^[a-f0-9]{64}$/u),
+    sourceRevision: z.string().regex(/^[a-f0-9]{64}$/u),
+    nextIndex: z.number().int().nonnegative(),
+    completedHash: z.string().regex(/^[a-f0-9]{64}$/u),
+    failed: z.number().int().nonnegative(),
+    unresolved: z.number().int().nonnegative(),
+})
+    .strict();
+function issueToken(engine, payload) {
+    const state = engine.resolver.serverState();
+    if (state === undefined)
+        throw new ServiceError('SCENARIO_CONTINUATION_UNAVAILABLE', 'Persistent server state is required for suite continuation');
+    const encoded = Buffer.from(canonicalJson(payload)).toString('base64url');
+    return `${encoded}.${state.authenticateJournal(payload)}`;
+}
+function readToken(engine, token) {
+    const state = engine.resolver.serverState();
+    if (state === undefined)
+        throw new ServiceError('SCENARIO_CONTINUATION_UNAVAILABLE', 'Persistent server state is required for suite continuation');
+    const [encoded, tag, extra] = token.split('.');
+    if (encoded === undefined || tag === undefined || extra !== undefined)
+        throw new ServiceError('SCENARIO_CONTINUATION_INVALID', 'Malformed continuation');
+    let payload;
+    try {
+        payload = continuationSchema.parse(JSON.parse(Buffer.from(encoded, 'base64url').toString('utf8')));
+    }
+    catch {
+        throw new ServiceError('SCENARIO_CONTINUATION_INVALID', 'Malformed continuation');
+    }
+    if (!state.verifyJournal(payload, tag))
+        throw new ServiceError('SCENARIO_CONTINUATION_INVALID', 'Continuation authentication failed');
+    return payload;
+}
+function atPath(object, path) {
+    let cursor = object;
+    for (const key of path) {
+        if (cursor === null || typeof cursor !== 'object' || !Object.hasOwn(cursor, key))
+            return undefined;
+        cursor = cursor[key];
+    }
+    return cursor;
+}
+function caseAssertions(assertions, output) {
+    return assertions.map((assertion) => {
+        const observed = atPath(output, assertion.path);
+        return {
+            id: assertion.id,
+            status: observed === undefined
+                ? 'unresolved'
+                : observed === assertion.expected
+                    ? 'passed'
+                    : 'failed',
+            ...(observed === undefined ? {} : { observed }),
+        };
+    });
+}
+function typedOperations(engine) {
+    const operations = new JobOperations();
+    registerAnalysisJobs(operations, engine);
+    registerEventJobs(operations, engine);
+    registerTechnologyJobs(operations, engine);
+    registerProbabilityJobs(operations, engine);
+    registerFocusJobs(operations, engine);
+    registerGuiJobs(operations, engine);
+    registerMapJobs(operations, engine);
+    return operations;
+}
+/**
+ * Runs a versioned suite in bounded pages through fixed read-only core
+ * operations. The continuation is signed and pins all selection inputs.
+ */
+export class ScenarioAnalyzer {
+    engine;
+    constructor(engine) {
+        this.engine = engine;
+    }
+    async test(input) {
+        const workspace = this.engine.resolver.get(input.workspaceId, input.principal);
+        if (input.refresh)
+            this.engine.invalidate(input.workspaceId);
+        const snapshot = await this.engine.scan(input.workspaceId, {}, input.principal, input.signal);
+        if (input.expectedRevision !== undefined && input.expectedRevision !== snapshot.revision)
+            throw new ServiceError('SCENARIO_SOURCE_STALE', 'Scenario source revision changed');
+        let suite;
+        let suiteFileHash;
+        if (input.suitePath !== undefined) {
+            const resolved = await this.engine.resolver.resolvePath(input.workspaceId, input.suitePath, 'read', ['mod'], input.principal);
+            const details = await stat(resolved.path);
+            if (!details.isFile() || details.size > MAX_SUITE_BYTES)
+                throw new ServiceError('SCENARIO_SUITE_LIMIT', 'Suite file exceeds the bounded reader');
+            const bytes = await readFile(resolved.path);
+            suiteFileHash = sha256Bytes(bytes);
+            suite = scenarioSuiteSchema.parse(JSON.parse(bytes.toString('utf8')));
+        }
+        else
+            suite = scenarioSuiteSchema.parse(input.suite);
+        const suiteHash = hashCanonical({ suite, suiteFileHash });
+        const resumed = input.continuation === undefined ? undefined : readToken(this.engine, input.continuation);
+        if (resumed !== undefined &&
+            (resumed.workspaceIdentity !== workspace.workspaceIdentity ||
+                resumed.principal !== (input.principal ?? '') ||
+                resumed.suiteHash !== suiteHash ||
+                resumed.sourceRevision !== snapshot.revision ||
+                resumed.nextIndex >= suite.cases.length ||
+                resumed.failed + resumed.unresolved > resumed.nextIndex))
+            throw new ServiceError('SCENARIO_CONTINUATION_STALE', 'Continuation does not match the authorized suite and source revision');
+        const start = resumed?.nextIndex ?? 0;
+        const end = Math.min(suite.cases.length, start + input.maxCases);
+        const operations = typedOperations(this.engine);
+        const packageAnalyzer = new PackageAnalyzer(this.engine);
+        const caseResults = [];
+        let completedHash = resumed?.completedHash ??
+            hashCanonical({
+                suiteHash,
+                sourceRevision: snapshot.revision,
+                workspaceIdentity: workspace.workspaceIdentity,
+            });
+        const evidence = analysisSourceEvidence(snapshot);
+        for (let index = start; index < end; index += 1) {
+            input.signal?.throwIfAborted();
+            const item = suite.cases[index];
+            const missing = item.sourceSelectors.filter(({ kind, id }) => snapshot.index.find(kind, id) === undefined);
+            let output;
+            let executionStatus;
+            let reason;
+            if (missing.length > 0) {
+                executionStatus = snapshot.complete ? 'failed' : 'unresolved';
+                reason = 'Declared source selector is absent from the active source index';
+                output = { missing };
+            }
+            else {
+                try {
+                    if (item.domain === 'mechanic') {
+                        const mechanic = runMechanicCase(snapshot, item.test);
+                        output = mechanic;
+                        executionStatus =
+                            mechanic.status === 'passed'
+                                ? 'completed'
+                                : mechanic.status === 'failed'
+                                    ? 'failed'
+                                    : 'unresolved';
+                    }
+                    else if (item.domain === 'package') {
+                        const checked = await packageAnalyzer.check({
+                            workspaceId: input.workspaceId,
+                            manifest: item.manifest,
+                            expectedRevision: snapshot.revision,
+                            ...(input.principal === undefined ? {} : { principal: input.principal }),
+                            ...(input.signal === undefined ? {} : { signal: input.signal }),
+                            refresh: false,
+                        });
+                        output = checked;
+                        executionStatus = checked.data.complete ? 'completed' : 'failed';
+                    }
+                    else {
+                        const operation = operations.get(item.tool);
+                        if (operation.mutation)
+                            throw new ServiceError('SCENARIO_TOOL_MUTATION', 'Suite operation is not read-only');
+                        const context = {
+                            engine: this.engine,
+                            workspaceId: input.workspaceId,
+                            principal: input.principal,
+                            signal: input.signal ?? new AbortController().signal,
+                            checkpoint: undefined,
+                            progress: () => Promise.resolve(),
+                            saveCheckpoint: () => Promise.reject(new ServiceError('SCENARIO_CHECKPOINT_UNAVAILABLE', 'Nested jobs cannot publish a suite checkpoint')),
+                            stageResult: () => Promise.resolve(),
+                        };
+                        const wire = await operation.run({
+                            ...item.arguments,
+                            workspaceId: input.workspaceId,
+                        }, context);
+                        output = atPath(wire, ['structuredContent']) ?? wire;
+                        const status = atPath(output, ['status']);
+                        const passed = atPath(output, ['validation', 'passed']);
+                        executionStatus =
+                            status === 'error' || status === 'blocked' || passed === false
+                                ? 'failed'
+                                : 'completed';
+                    }
+                }
+                catch (error) {
+                    if (input.signal?.aborted)
+                        throw error;
+                    executionStatus = 'unresolved';
+                    reason =
+                        error instanceof ServiceError
+                            ? error.code
+                            : error instanceof Error
+                                ? error.message
+                                : 'Case execution failed';
+                    output = {};
+                }
+            }
+            const assertions = caseAssertions(item.assertions, output);
+            const status = assertions.some(({ status }) => status === 'failed')
+                ? 'failed'
+                : assertions.some(({ status }) => status === 'unresolved') ||
+                    executionStatus === 'unresolved'
+                    ? 'unresolved'
+                    : executionStatus === 'failed'
+                        ? 'failed'
+                        : 'completed';
+            const caseReport = {
+                schemaVersion: 'scenario-case.v1',
+                suiteId: suite.id,
+                caseId: item.id,
+                index,
+                domain: item.domain,
+                sourceRevision: snapshot.revision,
+                status,
+                assertions,
+                ...(reason === undefined ? {} : { reason }),
+                output,
+            };
+            const caseHash = hashCanonical(caseReport);
+            const artifact = await this.engine.artifacts.putChunked(workspace, `scenario-case-${caseHash.slice(0, 24)}.json`, 'application/json', `${canonicalJson(caseReport)}\n`, {
+                kind: 'scenario-case',
+                toolVersion: PACKAGE_VERSION,
+                schemaVersion: 'scenario-case.v1',
+                sourceHashes: evidence.sourceHashes,
+                metadata: { beforeRevision: snapshot.revision, suiteHash, caseId: item.id },
+            }, 'Content-addressed suite case result', input.signal);
+            completedHash = hashCanonical({ prior: completedHash, caseId: item.id, caseHash });
+            caseResults.push({
+                id: item.id,
+                index,
+                status,
+                caseHash,
+                artifact: publicArtifactLink(artifact),
+                ...(item.views.includes('summary') ? { assertions } : {}),
+                ...(item.views.includes('artifacts')
+                    ? { outputArtifacts: atPath(output, ['artifacts']) }
+                    : {}),
+                ...(item.views.includes('diagnostics')
+                    ? { diagnostics: atPath(output, ['diagnostics']) }
+                    : {}),
+            });
+            const observed = await this.engine.scan(input.workspaceId, {}, input.principal, input.signal);
+            if (observed.revision !== snapshot.revision)
+                throw new ServiceError('SCENARIO_SOURCE_STALE', 'Source changed during suite execution');
+        }
+        const failed = (resumed?.failed ?? 0) + caseResults.filter(({ status }) => status === 'failed').length;
+        const unresolved = (resumed?.unresolved ?? 0) +
+            caseResults.filter(({ status }) => status === 'unresolved').length;
+        const continuation = end < suite.cases.length
+            ? issueToken(this.engine, {
+                version: 1,
+                workspaceIdentity: workspace.workspaceIdentity,
+                principal: input.principal ?? '',
+                suiteHash,
+                sourceRevision: snapshot.revision,
+                nextIndex: end,
+                completedHash,
+                failed,
+                unresolved,
+            })
+            : undefined;
+        const report = {
+            schemaVersion: 'scenario-suite-batch.v1',
+            suiteId: suite.id,
+            suiteHash,
+            sourceRevision: snapshot.revision,
+            start,
+            end,
+            total: suite.cases.length,
+            completedHash,
+            failed,
+            unresolved,
+            cases: caseResults,
+            ...(continuation === undefined ? {} : { continuation }),
+        };
+        const reportHash = hashCanonical(report);
+        const artifact = await this.engine.artifacts.putChunked(workspace, `scenario-batch-${reportHash.slice(0, 24)}.json`, 'application/json', `${canonicalJson(report)}\n`, {
+            kind: 'scenario-suite-batch',
+            toolVersion: PACKAGE_VERSION,
+            schemaVersion: 'scenario-suite-batch.v1',
+            sourceHashes: evidence.sourceHashes,
+            metadata: { beforeRevision: snapshot.revision, suiteHash, start, end },
+        }, 'Revision-pinned suite batch and continuation evidence', input.signal);
+        const result = emptyServiceResult(input.workspaceId, {
+            sourceRevision: snapshot.revision,
+            suiteHash,
+            reportHash,
+            start,
+            end,
+            total: suite.cases.length,
+            completed: end,
+            failed,
+            unresolved,
+            pending: suite.cases.length - end,
+            ...(continuation === undefined ? {} : { continuation }),
+        });
+        result.code =
+            continuation !== undefined
+                ? 'SCENARIO_SUITE_PENDING'
+                : failed > 0 || unresolved > 0
+                    ? 'SCENARIO_SUITE_INCOMPLETE'
+                    : 'SCENARIO_SUITE_PASSED';
+        result.artifacts = [publicArtifactLink(artifact)];
+        setInlineFilesScanned(result, snapshot.files.map(({ displayPath }) => displayPath));
+        result.validation = {
+            passed: continuation === undefined && failed === 0 && unresolved === 0,
+            checks: [
+                {
+                    id: 'suite-cases',
+                    passed: continuation === undefined && failed === 0 && unresolved === 0,
+                    message: continuation === undefined
+                        ? 'All requested cases were reported in this suite'
+                        : 'Additional cases are pending under the authenticated continuation',
+                },
+            ],
+        };
+        return result;
+    }
+}

package/dist/hoi4_agent_tools/schemas/event.js

@@ -151,6 +151,12 @@ export function validateEventCompareRequest(value, context) {
             path: ['after'],
             message: 'after and proposedSources are mutually exclusive',
         });
+    if (value.maxChainNodes !== undefined && value.selector === undefined)
+        context.addIssue({
+            code: 'custom',
+            path: ['maxChainNodes'],
+            message: 'maxChainNodes requires selector',
+        });
 }
 export const eventCompareRequestSchema = z
     .object({
@@ -158,6 +164,8 @@ export const eventCompareRequestSchema = z
     before: eventGraphReferenceSchema.optional(),
     after: eventGraphReferenceSchema.optional(),
     proposedSources: z.array(eventProposedSourceSchema).min(1).max(64).optional(),
+    selector: eventSelectorSchema.optional(),
+    maxChainNodes: z.number().int().min(1).max(5_000).optional(),
     render: z.boolean().optional(),
     maxRenderNodes: z.number().int().min(1).max(240).optional(),
     refresh: z.boolean().optional(),

package/dist/hoi4_agent_tools/schemas/focus-requests.js

@@ -17,6 +17,10 @@ export const focusInspectRequestSchema = z
     previous: compactFocusLayoutSchema.optional(),
     laneSpacing: z.number().int().min(1).max(100).optional(),
     nodeSpacing: z.number().int().min(1).max(100).optional(),
+    scenario: z
+        .object({ completedFocusIds: z.array(z.string().min(1).max(256)).max(10_000) })
+        .strict()
+        .optional(),
 })
     .strict()
     .superRefine((value, context) => {
@@ -34,7 +38,7 @@ export const focusInspectRequestSchema = z
             message: 'treeId is only valid in national mode',
         });
     if (mode === 'continuous') {
-        for (const field of ['previous', 'laneSpacing', 'nodeSpacing']) {
+        for (const field of ['previous', 'laneSpacing', 'nodeSpacing', 'scenario']) {
             if (value[field] !== undefined)
                 context.addIssue({
                     code: 'custom',
@@ -49,6 +53,12 @@ export const focusInspectRequestSchema = z
             path: ['previous'],
             message: 'previous requires treeId so it applies to exactly one tree',
         });
+    if (value.scenario !== undefined && value.treeId === undefined)
+        context.addIssue({
+            code: 'custom',
+            path: ['scenario'],
+            message: 'scenario requires treeId so it applies to exactly one tree',
+        });
 });
 export const focusRenderRequestSchema = z
     .object({
@@ -64,6 +74,7 @@ export const focusRenderRequestSchema = z
         .min(FOCUS_RENDER_MIN_OUTPUT_SCALE)
         .max(FOCUS_RENDER_MAX_OUTPUT_SCALE)
         .optional(),
+    cropFocusIds: z.array(z.string().min(1).max(256)).max(16).optional(),
     columns: z.number().int().min(1).max(12).optional(),
     padding: z.number().int().min(0).max(1000).optional(),
 })
@@ -80,6 +91,7 @@ export const focusRenderRequestSchema = z
             ['horizontalSpacing', value.horizontalSpacing],
             ['verticalSpacing', value.verticalSpacing],
             ['reviewScale', value.reviewScale],
+            ['cropFocusIds', value.cropFocusIds],
         ];
     for (const [field, fieldValue] of invalid) {
         if (fieldValue !== undefined)
@@ -103,6 +115,25 @@ export const focusRewriteRequestSchema = z
     relativePath: workspaceRelativePathSchema,
     treeId: z.string().min(1).max(256).optional(),
     layoutMode: z.enum(['authored', 'compact']).default('authored'),
+    compactFocusIds: z.array(z.string().min(1).max(256)).min(1).max(10_000).optional(),
+    pinnedFocusIds: z.array(z.string().min(1).max(256)).max(10_000).optional(),
+    symmetryGroups: z
+        .array(z
+        .object({
+        centerFocusId: z.string().min(1).max(256),
+        pairs: z
+            .array(z
+            .object({
+            leftFocusId: z.string().min(1).max(256),
+            rightFocusId: z.string().min(1).max(256),
+        })
+            .strict())
+            .min(1)
+            .max(10_000),
+    })
+        .strict())
+        .max(64)
+        .optional(),
     plan: compactFocusPlanSchema.optional(),
     createIfMissing: z.boolean().default(false),
     horizontalSpacing: z.number().int().min(80).max(1000).optional(),
@@ -117,6 +148,14 @@ export const focusRewriteRequestSchema = z
 })
     .strict()
     .superRefine((value, context) => {
+    if (value.layoutMode !== 'compact')
+        for (const field of ['compactFocusIds', 'pinnedFocusIds', 'symmetryGroups'])
+            if (value[field] !== undefined)
+                context.addIssue({
+                    code: 'custom',
+                    path: [field],
+                    message: `${field} requires compact layout mode`,
+                });
     const mode = value.mode ?? 'national';
     const schema = mode === 'continuous' ? continuousFocusPaletteSchema : focusTreePlanSchema;
     if (value.plan !== undefined && !schema.safeParse(value.plan).success)

package/dist/hoi4_agent_tools/schemas/gui-requests.js

@@ -82,6 +82,14 @@ export const guiRenderRequestSchema = z
     relatedScenarios: z.array(compactGuiScenarioSchema).max(32).optional(),
     generatedScenarios: compactGeneratedScenarioOptionsSchema.optional(),
     comparisonScenario: compactGuiScenarioSchema.optional(),
+    sourceBaseline: z
+        .object({
+        relativePath: workspaceRelativePathSchema,
+        source: z.string().max(SOURCE_MAX_BYTES),
+    })
+        .strict()
+        .optional()
+        .describe('Previous mod-owned .gui source for a matched source comparison using the requested scenario.'),
 })
     .strict()
     .superRefine(({ scenario, states, resolutions, relatedScenarios, generatedScenarios }, context) => {

package/dist/hoi4_agent_tools/schemas/map-requests.js

@@ -63,6 +63,7 @@ export const mapInspectRequestSchema = z
     ]))
         .max(100)
         .default([]),
+    lookupOnly: z.boolean().default(false),
     includeOverview: z.boolean().default(true),
     allocationRequests: z.array(mapAllocationRequestSchema).max(100).default([]),
 })
@@ -73,8 +74,28 @@ export const mapRenderRequestSchema = z
     layer: mapLayerSchema.optional(),
     overlays: z.array(mapOverlaySchema).max(12).optional(),
     scale: z.number().int().min(1).max(16).optional(),
+    tile: z
+        .object({
+        x: z.number().int().min(0),
+        y: z.number().int().min(0),
+        width: z.number().int().min(1).max(2_048),
+        height: z.number().int().min(1).max(2_048),
+    })
+        .strict()
+        .optional(),
+    area: z
+        .object({
+        provinceIds: z.array(z.number().int().nonnegative()).max(256).optional(),
+        stateIds: z.array(z.number().int().nonnegative()).max(64).optional(),
+        regionIds: z.array(z.number().int().nonnegative()).max(64).optional(),
+        padding: z.number().int().min(0).max(256).optional(),
+    })
+        .strict()
+        .refine(({ provinceIds, stateIds, regionIds }) => (provinceIds?.length ?? 0) + (stateIds?.length ?? 0) + (regionIds?.length ?? 0) > 0, 'Map area requires at least one province, state, or region ID')
+        .optional(),
 })
-    .strict();
+    .strict()
+    .refine(({ tile, area }) => tile === undefined || area === undefined, 'Choose tile or area, not both');
 export const mapRewriteRequestSchema = z
     .object({
     workspaceId: workspaceIdSchema,