hoi4-agent-tools 3.2.0 → 3.3.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/scenarios.js

@@ -0,0 +1,264 @@
+import { z } from 'zod/v4';
+import { declaredConditionScenarioSchema } from './analysis.js';
+import { workspaceIdSchema, workspaceRelativePathSchema } from './common.js';
+const identifier = z.string().min(1).max(512);
+const manifestToken = z.string().regex(/^[A-Za-z0-9_.:-]{1,512}$/u);
+const sourceSelector = z
+    .object({
+    kind: z.enum(['scripted_effect', 'event_option', 'decision', 'focus_reward']),
+    id: identifier,
+    option: identifier.optional(),
+})
+    .strict();
+export const sharedScenarioSchema = declaredConditionScenarioSchema.safeExtend({
+    schemaVersion: z.literal('1.0'),
+    globalFlags: z.array(identifier).max(10_000).optional(),
+    scopeCatalogs: z
+        .record(identifier, z
+        .object({
+        complete: z.boolean(),
+        members: z.array(identifier).max(2_048),
+    })
+        .strict())
+        .optional(),
+});
+const assertionPath = z
+    .object({
+    scope: identifier.default('ROOT'),
+    key: identifier,
+})
+    .strict();
+const scalar = z.union([z.string().max(4_096), z.number(), z.boolean(), z.null()]);
+export const mechanicAssertionSchema = z.discriminatedUnion('kind', [
+    z
+        .object({ id: identifier, kind: z.literal('equals'), path: assertionPath, expected: scalar })
+        .strict(),
+    z
+        .object({
+        id: identifier,
+        kind: z.literal('conservation'),
+        paths: z.array(assertionPath).min(2).max(64),
+        tolerance: z.number().nonnegative().default(0),
+    })
+        .strict(),
+    z
+        .object({
+        id: identifier,
+        kind: z.literal('array_alignment'),
+        paths: z.array(assertionPath).min(2).max(32),
+    })
+        .strict(),
+    z
+        .object({
+        id: identifier,
+        kind: z.literal('affordability'),
+        balance: assertionPath,
+        cost: z.number().nonnegative(),
+    })
+        .strict(),
+    z
+        .object({
+        id: identifier,
+        kind: z.literal('single_payment'),
+        balance: assertionPath,
+        cost: z.number().nonnegative(),
+    })
+        .strict(),
+    z
+        .object({
+        id: identifier,
+        kind: z.literal('repeated_setup'),
+        firstStep: z.number().int().nonnegative(),
+        secondStep: z.number().int().nonnegative(),
+    })
+        .strict(),
+    z
+        .object({
+        id: identifier,
+        kind: z.literal('exclusive_flags'),
+        scope: identifier.default('ROOT'),
+        flags: z.array(identifier).min(2).max(64),
+    })
+        .strict(),
+    z
+        .object({
+        id: identifier,
+        kind: z.literal('cleanup'),
+        scope: identifier.default('ROOT'),
+        flags: z.array(identifier).max(64).default([]),
+        targets: z.array(identifier).max(64).default([]),
+    })
+        .strict(),
+    z
+        .object({ id: identifier, kind: z.literal('end_state'), path: assertionPath, expected: scalar })
+        .strict(),
+]);
+export const mechanicCaseSchema = z
+    .object({
+    id: identifier,
+    scenario: sharedScenarioSchema,
+    steps: z
+        .array(z.discriminatedUnion('kind', [
+        z
+            .object({
+            kind: z.literal('effect'),
+            source: sourceSelector,
+            repeat: z.number().int().min(1).max(8).default(1),
+        })
+            .strict(),
+        z
+            .object({ kind: z.literal('advance_days'), days: z.number().int().min(0).max(36_500) })
+            .strict(),
+    ]))
+        .min(1)
+        .max(128),
+    assertions: z.array(mechanicAssertionSchema).min(1).max(256),
+})
+    .strict();
+export const mechanicTestRequestSchema = z
+    .object({
+    workspaceId: workspaceIdSchema,
+    test: mechanicCaseSchema,
+    expectedRevision: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .optional(),
+    refresh: z.boolean().default(false),
+})
+    .strict();
+const manifestItem = z.object({ kind: manifestToken, id: manifestToken }).strict();
+export const packageManifestSchema = z
+    .object({
+    schemaVersion: z.literal('1.0'),
+    id: manifestToken,
+    definitions: z.array(manifestItem).max(2_048).default([]),
+    calls: z
+        .array(z.object({ from: manifestItem, to: manifestItem }).strict())
+        .max(2_048)
+        .default([]),
+    registrations: z
+        .array(z.object({ path: workspaceRelativePathSchema, token: manifestToken }).strict())
+        .max(2_048)
+        .default([]),
+    localisation: z.array(manifestToken).max(2_048).default([]),
+    assets: z.array(workspaceRelativePathSchema).max(2_048).default([]),
+    requiredCases: z
+        .array(z.object({ suite: workspaceRelativePathSchema, caseId: manifestToken }).strict())
+        .max(512)
+        .default([]),
+})
+    .strict();
+export const packageCheckRequestSchema = z
+    .object({
+    workspaceId: workspaceIdSchema,
+    manifest: packageManifestSchema,
+    expectedRevision: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .optional(),
+    refresh: z.boolean().default(false),
+})
+    .strict();
+const readOnlySuiteTool = z.enum([
+    'hoi4.impact_inspect',
+    'hoi4.decision_inspect',
+    'hoi4.event_inspect',
+    'hoi4.event_render',
+    'hoi4.tech_inspect',
+    'hoi4.tech_render',
+    'hoi4.probability_inspect',
+    'hoi4.probability_evaluate',
+    'hoi4.probability_render',
+    'hoi4.focus_inspect',
+    'hoi4.focus_render',
+    'hoi4.gui_inspect',
+    'hoi4.gui_render',
+    'hoi4.map_inspect',
+    'hoi4.map_render',
+]);
+const suiteCaseMetadata = {
+    sourceSelectors: z.array(manifestItem).max(64).default([]),
+    assertions: z
+        .array(z
+        .object({
+        id: identifier,
+        path: z.array(identifier).min(1).max(16),
+        expected: scalar,
+    })
+        .strict())
+        .max(64)
+        .default([]),
+    views: z
+        .array(z.enum(['summary', 'artifacts', 'diagnostics']))
+        .max(3)
+        .default(['summary']),
+};
+export const scenarioSuiteSchema = z
+    .object({
+    schemaVersion: z.literal('1.0'),
+    id: identifier,
+    cases: z
+        .array(z.discriminatedUnion('domain', [
+        z
+            .object({
+            domain: z.literal('mechanic'),
+            id: identifier,
+            test: mechanicCaseSchema,
+            ...suiteCaseMetadata,
+        })
+            .strict(),
+        z
+            .object({
+            domain: z.literal('package'),
+            id: identifier,
+            manifest: packageManifestSchema,
+            ...suiteCaseMetadata,
+        })
+            .strict(),
+        z
+            .object({
+            domain: z.literal('tool'),
+            id: identifier,
+            tool: readOnlySuiteTool,
+            arguments: z.record(z.string().max(256), z.json()),
+            ...suiteCaseMetadata,
+        })
+            .strict(),
+    ]))
+        .min(1)
+        .max(10_000),
+})
+    .strict()
+    .superRefine((suite, context) => {
+    const ids = new Set();
+    for (const [index, item] of suite.cases.entries()) {
+        if (ids.has(item.id))
+            context.addIssue({
+                code: 'custom',
+                path: ['cases', index, 'id'],
+                message: 'Suite case ids must be unique',
+            });
+        ids.add(item.id);
+    }
+});
+export const scenarioTestRequestSchema = z
+    .object({
+    workspaceId: workspaceIdSchema,
+    suite: scenarioSuiteSchema.optional(),
+    suitePath: workspaceRelativePathSchema.optional(),
+    continuation: z.string().max(4_096).optional(),
+    maxCases: z.number().int().min(1).max(256).default(32),
+    expectedRevision: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .optional(),
+    refresh: z.boolean().default(false),
+})
+    .strict()
+    .superRefine((input, context) => {
+    if ((input.suite === undefined) === (input.suitePath === undefined))
+        context.addIssue({
+            code: 'custom',
+            message: 'Specify exactly one inline suite or suitePath',
+        });
+});

package/dist/hoi4_agent_tools/version.js

@@ -1,6 +1,6 @@
 import { LATEST_PROTOCOL_VERSION } from '@modelcontextprotocol/sdk/types.js';
 export const PACKAGE_NAME = 'hoi4-agent-tools';
-export const PACKAGE_VERSION = '3.2.0';
+export const PACKAGE_VERSION = '3.3.0';
 export const MCP_PROTOCOL_VERSION = LATEST_PROTOCOL_VERSION;
 export const CONFIG_VERSION = 1;
 export const TRANSACTION_VERSION = 1;

package/docs/README.md

@@ -3,6 +3,7 @@
 - [Setup](setup.md): install the server, configure HOI4 paths, and connect an MCP client.
 - [Event chains](events.md): inspect, trace, lint, render, and compare event chains.
 - [Cross-system impact and decisions](analysis.md): trace source consumers and evaluate decision or mission scenarios.
+- [Mechanic tests and scenario suites](mechanics.md): interpret declared effect steps, check package links, and run resumable cases.
 - [Technology trees](technology.md): inspect, trace, lint, render, and compare technologies and doctrines.
 - [Bounded helper expansion](helper-expansion.md): resume source-linked event and technology helper paths with exact coverage boundaries.
 - [Persistent jobs](jobs.md): run, inspect, cancel, and recover long operations.