hoi4-agent-tools 3.1.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/analysis.js

@@ -0,0 +1,228 @@
+import { z } from 'zod/v4';
+import { workspaceIdSchema, workspaceRelativePathSchema } from './common.js';
+const symbolKindSchema = z.enum([
+    'focus_tree',
+    'focus',
+    'continuous_focus_palette',
+    'continuous_focus',
+    'decision',
+    'decision_category',
+    'event',
+    'idea',
+    'leader',
+    'formable',
+    'scripted_effect',
+    'scripted_trigger',
+    'script_constant',
+    'mtth_variable',
+    'ai_strategy',
+    'ai_strategy_plan',
+    'sprite',
+    'texture',
+    'gui_element',
+    'scripted_gui',
+    'technology',
+    'technology_folder',
+    'technology_category',
+    'technology_tag',
+    'equipment',
+    'equipment_module',
+    'sub_unit',
+    'unit_category',
+    'building',
+    'ability',
+    'combat_tactic',
+    'doctrine_folder',
+    'grand_doctrine',
+    'doctrine_track',
+    'subdoctrine',
+    'localisation',
+    'variable',
+    'flag',
+    'event_target',
+    'state',
+    'province',
+    'province_color',
+    'strategic_region',
+    'adjacency',
+    'supply_node',
+    'railway',
+]);
+export const impactSymbolSelectorSchema = z
+    .object({
+    kind: symbolKindSchema,
+    id: z.string().min(1).max(512),
+})
+    .strict();
+const sourceDisplayPathSchema = z
+    .string()
+    .min(1)
+    .max(4096)
+    .refine((value) => {
+    const separator = value.indexOf(':');
+    if (separator < 1)
+        return false;
+    const root = value.slice(0, separator);
+    if (!/^(?:mod|game|fixture|dependency-[0-9]+)$/u.test(root))
+        return false;
+    return workspaceRelativePathSchema.safeParse(value.slice(separator + 1)).success;
+}, 'Use a scanned source display path under an authorized workspace root');
+export const proposedAnalysisSourceSchema = z
+    .object({
+    relativePath: workspaceRelativePathSchema,
+    content: z
+        .string()
+        .max(8 * 1024 * 1024)
+        .nullable(),
+})
+    .strict();
+const scenarioScalarSchema = z.union([z.string().max(4096), z.number(), z.boolean(), z.null()]);
+const scenarioValueSchema = z.union([
+    scenarioScalarSchema,
+    z.array(scenarioScalarSchema).max(10_000),
+]);
+const scenarioStateSchema = z
+    .record(z.string().min(1).max(1024), scenarioValueSchema)
+    .refine((state) => Object.keys(state).length <= 10_000, 'Scenario state has too many keys');
+const scopeBindingSchema = z
+    .object({
+    id: z.string().min(1).max(512),
+    type: z
+        .enum([
+        'country',
+        'state',
+        'character',
+        'unit_leader',
+        'operative',
+        'strategic_region',
+        'province',
+        'unknown',
+    ])
+        .optional(),
+    actor: z.string().max(256).optional(),
+    state: scenarioStateSchema,
+    flags: z.array(z.string().min(1).max(512)).max(10_000).optional(),
+    eventTargets: z.record(z.string().max(512), z.string().max(512)).optional(),
+    weight: z.union([z.number(), z.string().max(1024)]).optional(),
+})
+    .strict();
+export const declaredConditionScenarioSchema = z
+    .object({
+    id: z.string().min(1).max(512),
+    actor: z.string().max(256).optional(),
+    date: z.string().max(64).optional(),
+    state: scenarioStateSchema,
+    flags: z.array(z.string().min(1).max(512)).max(10_000).optional(),
+    eventTargets: z.record(z.string().max(512), z.string().max(512)).optional(),
+    scopes: z
+        .record(z.string().min(1).max(128), scopeBindingSchema)
+        .refine((scopes) => Object.keys(scopes).length <= 64, 'Too many declared scopes')
+        .optional(),
+    candidateOverrides: z.record(z.string().max(512), z.boolean()).optional(),
+    closedFlags: z.boolean().optional(),
+})
+    .strict();
+export const impactInspectRequestSchema = z
+    .object({
+    workspaceId: workspaceIdSchema,
+    symbols: z.array(impactSymbolSelectorSchema).max(64).default([]),
+    changedFiles: z.array(sourceDisplayPathSchema).max(64).default([]),
+    scenarioSuites: z
+        .array(workspaceRelativePathSchema.refine((value) => value.toLowerCase().endsWith('.json'), 'Scenario suite path must name a JSON file'))
+        .max(32)
+        .default([]),
+    proposedSources: z.array(proposedAnalysisSourceSchema).min(1).max(64).optional(),
+    maxNodes: z.number().int().min(1).max(50_000).optional(),
+    maxEdges: z.number().int().min(1).max(100_000).optional(),
+    maxDepth: z.number().int().min(1).max(64).optional(),
+    expectedRevision: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .optional(),
+    refresh: z.boolean().default(false),
+})
+    .strict()
+    .superRefine((input, context) => {
+    if (input.symbols.length === 0 &&
+        input.changedFiles.length === 0 &&
+        input.proposedSources === undefined)
+        context.addIssue({
+            code: 'custom',
+            message: 'Impact inspection requires a symbol, changed file, or proposed source',
+        });
+});
+export const decisionInspectRequestSchema = z
+    .object({
+    workspaceId: workspaceIdSchema,
+    mode: z.enum(['inventory', 'inspect', 'compare']).default('inventory'),
+    id: z.string().min(1).max(512).optional(),
+    scenarios: z.array(declaredConditionScenarioSchema).max(64).default([]),
+    proposedSources: z.array(proposedAnalysisSourceSchema).min(1).max(64).optional(),
+    expectedRevision: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .optional(),
+    refresh: z.boolean().default(false),
+})
+    .strict()
+    .superRefine((input, context) => {
+    const ids = new Set();
+    for (const [index, scenario] of input.scenarios.entries()) {
+        if (ids.has(scenario.id))
+            context.addIssue({
+                code: 'custom',
+                path: ['scenarios', index, 'id'],
+                message: 'Scenario IDs must be unique',
+            });
+        ids.add(scenario.id);
+    }
+    if (input.mode === 'inventory') {
+        if (input.proposedSources !== undefined)
+            context.addIssue({
+                code: 'custom',
+                path: ['proposedSources'],
+                message: 'Inventory mode does not accept proposed sources',
+            });
+        return;
+    }
+    if (input.id === undefined)
+        context.addIssue({
+            code: 'custom',
+            path: ['id'],
+            message: 'Decision inspection requires an identifier',
+        });
+    if (input.scenarios.length === 0)
+        context.addIssue({
+            code: 'custom',
+            path: ['scenarios'],
+            message: 'Decision inspection requires declared scenarios',
+        });
+    if (input.mode === 'compare' && input.proposedSources === undefined)
+        context.addIssue({
+            code: 'custom',
+            path: ['proposedSources'],
+            message: 'Decision comparison requires proposed sources',
+        });
+    if (input.mode === 'inspect' && input.proposedSources !== undefined)
+        context.addIssue({
+            code: 'custom',
+            path: ['proposedSources'],
+            message: 'Use compare mode for proposed sources',
+        });
+});
+/** A reference projection of future scenario suites; Stage 3 reads but never executes it. */
+export const impactScenarioSuiteReferenceSchema = z
+    .object({
+    schemaVersion: z.literal('1.0'),
+    id: z.string().min(1).max(512),
+    cases: z
+        .array(z
+        .object({
+        id: z.string().min(1).max(512),
+        sourceSelectors: z.array(impactSymbolSelectorSchema).max(64).default([]),
+        sourceFiles: z.array(sourceDisplayPathSchema).max(64).default([]),
+    })
+        .loose())
+        .max(1_000),
+})
+    .loose();