hoi4-agent-tools 3.1.0 → 3.3.0

package/dist/hoi4_agent_tools/mcp/tools/analysis.js

@@ -0,0 +1,155 @@
+import { z } from 'zod/v4';
+import { decisionInspectRequestSchema, impactInspectRequestSchema, } from '../../schemas/analysis.js';
+import { mechanicCaseSchema, mechanicTestRequestSchema, packageManifestSchema, packageCheckRequestSchema, scenarioSuiteSchema, scenarioTestRequestSchema, } from '../../schemas/scenarios.js';
+import { compactValidatedInputSchema } from '../server/context-schemas.js';
+import { nonNegativeIntegerSchema, sha256Schema } from '../server/output-schemas.js';
+import { strictOperationResultSchema } from '../server/result.js';
+import { registerLegacyTaskTools } from '../server/legacy-task-tools.js';
+const impactOutputSchema = strictOperationResultSchema(z
+    .object({
+    mode: z.enum(['inspect', 'compare']),
+    sourceRevision: sha256Schema,
+    proposedRevision: sha256Schema.optional(),
+    reportHash: sha256Schema,
+    complete: z.boolean(),
+    definitions: nonNegativeIntegerSchema,
+    directConsumers: nonNegativeIntegerSchema,
+    transitiveConsumers: nonNegativeIntegerSchema,
+    affectedFiles: nonNegativeIntegerSchema,
+    cycles: nonNegativeIntegerSchema,
+    scenarioSuites: nonNegativeIntegerSchema,
+    affectedCases: nonNegativeIntegerSchema,
+    unresolved: nonNegativeIntegerSchema,
+    addedConsumers: nonNegativeIntegerSchema.optional(),
+    removedConsumers: nonNegativeIntegerSchema.optional(),
+})
+    .strict());
+const decisionOutputSchema = strictOperationResultSchema(z
+    .object({
+    mode: z.enum(['inventory', 'inspect', 'compare']),
+    sourceRevision: sha256Schema,
+    proposedRevision: sha256Schema.optional(),
+    reportHash: sha256Schema,
+    complete: z.boolean(),
+    decisions: nonNegativeIntegerSchema,
+    categories: nonNegativeIntegerSchema,
+    overrides: nonNegativeIntegerSchema,
+    scenarios: nonNegativeIntegerSchema,
+    unresolvedDefinitions: nonNegativeIntegerSchema,
+})
+    .strict());
+const mechanicOutputSchema = strictOperationResultSchema(z
+    .object({
+    sourceRevision: sha256Schema,
+    reportHash: sha256Schema,
+    status: z.enum(['passed', 'failed', 'unresolved']),
+    assertions: nonNegativeIntegerSchema,
+    passed: nonNegativeIntegerSchema,
+    failed: nonNegativeIntegerSchema,
+    unresolved: nonNegativeIntegerSchema,
+    steps: nonNegativeIntegerSchema,
+})
+    .strict());
+const packageOutputSchema = strictOperationResultSchema(z
+    .object({
+    sourceRevision: sha256Schema,
+    reportHash: sha256Schema,
+    complete: z.boolean(),
+    items: nonNegativeIntegerSchema,
+    present: nonNegativeIntegerSchema,
+    absent: nonNegativeIntegerSchema,
+    shadowed: nonNegativeIntegerSchema,
+    unresolved: nonNegativeIntegerSchema,
+})
+    .strict());
+const scenarioOutputSchema = strictOperationResultSchema(z
+    .object({
+    sourceRevision: sha256Schema,
+    suiteHash: sha256Schema,
+    reportHash: sha256Schema,
+    start: nonNegativeIntegerSchema,
+    end: nonNegativeIntegerSchema,
+    total: nonNegativeIntegerSchema,
+    completed: nonNegativeIntegerSchema,
+    failed: nonNegativeIntegerSchema,
+    unresolved: nonNegativeIntegerSchema,
+    pending: nonNegativeIntegerSchema,
+    continuation: z.string().optional(),
+})
+    .strict());
+const mechanicInputSchema = z
+    .object({
+    ...mechanicTestRequestSchema.shape,
+    test: compactValidatedInputSchema(mechanicCaseSchema, 'Versioned declared scenario, explicit effect steps, and typed assertions. See docs/mechanics.md.'),
+})
+    .strict();
+const packageInputSchema = z
+    .object({
+    ...packageCheckRequestSchema.shape,
+    manifest: compactValidatedInputSchema(packageManifestSchema, 'Declarative definitions, calls, registrations, localisation, assets, and required cases. See docs/mechanics.md.'),
+})
+    .strict();
+const scenarioInputSchema = z
+    .object({
+    ...scenarioTestRequestSchema.shape,
+    suite: compactValidatedInputSchema(scenarioSuiteSchema, 'Named mechanic, package, or fixed read-only tool cases. See docs/mechanics.md.').optional(),
+})
+    .strict()
+    .superRefine((input, context) => {
+    if ((input.suite === undefined) === (input.suitePath === undefined))
+        context.addIssue({
+            code: 'custom',
+            message: 'Specify exactly one inline suite or suitePath',
+        });
+});
+const readOnlyAnalysisTool = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+};
+export const analysisTaskTools = [
+    {
+        name: 'hoi4.impact_inspect',
+        title: 'Inspect cross-system impact',
+        description: 'Trace definitions and consumers of symbols or changed source across HOI4 systems. Proposed sources are analyzed in memory; full revision-bound evidence is linked.',
+        inputSchema: impactInspectRequestSchema,
+        outputSchema: impactOutputSchema,
+        annotations: readOnlyAnalysisTool,
+    },
+    {
+        name: 'hoi4.decision_inspect',
+        title: 'Inspect decisions and missions',
+        description: 'Inventory decisions or evaluate declared actor and target scenarios for gates, payment, lifecycle, and proposed-source differences. Full evidence is linked.',
+        inputSchema: decisionInspectRequestSchema,
+        outputSchema: decisionOutputSchema,
+        annotations: readOnlyAnalysisTool,
+    },
+    {
+        name: 'hoi4.mechanic_test',
+        title: 'Test declared mechanic steps',
+        description: 'Interpret bounded, source-backed effect steps on isolated declared state and check typed invariants. Unsupported effects remain unresolved; no game or mod source is changed.',
+        inputSchema: mechanicInputSchema,
+        outputSchema: mechanicOutputSchema,
+        annotations: readOnlyAnalysisTool,
+    },
+    {
+        name: 'hoi4.package_check',
+        title: 'Check package connections',
+        description: 'Check a declarative package manifest against active definitions, references, registrations, localisation, assets, and required suite cases.',
+        inputSchema: packageInputSchema,
+        outputSchema: packageOutputSchema,
+        annotations: readOnlyAnalysisTool,
+    },
+    {
+        name: 'hoi4.scenario_test',
+        title: 'Run scenario suite',
+        description: 'Run named inline or workspace-relative cases through bounded typed read-only domain services. Large suites return an authenticated continuation.',
+        inputSchema: scenarioInputSchema,
+        outputSchema: scenarioOutputSchema,
+        annotations: readOnlyAnalysisTool,
+    },
+];
+export function registerAnalysisTools(server) {
+    registerLegacyTaskTools(server, analysisTaskTools);
+}

package/dist/hoi4_agent_tools/mechanic/assertions.js

@@ -0,0 +1,112 @@
+import { canonicalJson } from '../core/canonical.js';
+import { scenarioValue } from '../core/scenario-model.js';
+function value(state, path) {
+    return scenarioValue(state, path.key, path.scope);
+}
+function number(state, path) {
+    const found = value(state, path);
+    return typeof found === 'number' && Number.isFinite(found) ? found : undefined;
+}
+function result(assertion, status, observed, reason) {
+    return {
+        id: assertion.id,
+        kind: assertion.kind,
+        status,
+        ...(observed === undefined ? {} : { observed }),
+        ...(reason === undefined ? {} : { reason }),
+    };
+}
+export function evaluateMechanicAssertions(assertions, before, after, checkpoints, trace) {
+    return assertions.map((assertion) => {
+        if (before.unknown.has('*') || after.unknown.has('*'))
+            return result(assertion, 'unresolved', undefined, 'An unsupported effect may write this state');
+        if (assertion.kind === 'equals' || assertion.kind === 'end_state') {
+            const found = value(after, assertion.path);
+            if (found === undefined)
+                return result(assertion, 'unresolved', undefined, 'End-state value is unknown');
+            return result(assertion, found === assertion.expected ? 'passed' : 'failed', found);
+        }
+        if (assertion.kind === 'conservation') {
+            const starting = assertion.paths.map((path) => number(before, path));
+            const ending = assertion.paths.map((path) => number(after, path));
+            if ([...starting, ...ending].some((item) => item === undefined))
+                return result(assertion, 'unresolved', undefined, 'Conserved values must be declared numbers');
+            const initial = starting.reduce((sum, item) => sum + item, 0);
+            const final = ending.reduce((sum, item) => sum + item, 0);
+            return result(assertion, Math.abs(initial - final) <= assertion.tolerance ? 'passed' : 'failed', { initial, final, difference: final - initial });
+        }
+        if (assertion.kind === 'array_alignment') {
+            const arrays = assertion.paths.map((path) => value(after, path));
+            if (arrays.some((item) => !Array.isArray(item)))
+                return result(assertion, 'unresolved', undefined, 'All aligned values must be declared arrays');
+            const lengths = arrays.map((array) => array.length);
+            return result(assertion, lengths.every((length) => length === lengths[0]) ? 'passed' : 'failed', lengths);
+        }
+        if (assertion.kind === 'affordability') {
+            const available = number(before, assertion.balance);
+            return available === undefined
+                ? result(assertion, 'unresolved', undefined, 'Starting balance is unknown')
+                : result(assertion, available >= assertion.cost ? 'passed' : 'failed', {
+                    available,
+                    cost: assertion.cost,
+                });
+        }
+        if (assertion.kind === 'single_payment') {
+            const starting = number(before, assertion.balance);
+            const ending = number(after, assertion.balance);
+            const reductions = trace.flatMap((step) => step.status === 'applied' &&
+                step.scope === assertion.balance.scope &&
+                step.target === assertion.balance.key &&
+                typeof step.before === 'number' &&
+                typeof step.after === 'number' &&
+                step.before > step.after
+                ? [step.before - step.after]
+                : []);
+            return starting === undefined || ending === undefined
+                ? result(assertion, 'unresolved', undefined, 'Payment balance is unknown')
+                : result(assertion, reductions.length === 1 &&
+                    reductions[0] === assertion.cost &&
+                    starting - ending === assertion.cost
+                    ? 'passed'
+                    : 'failed', {
+                    paid: starting - ending,
+                    expected: assertion.cost,
+                    deductions: reductions,
+                });
+        }
+        if (assertion.kind === 'repeated_setup') {
+            const first = checkpoints[assertion.firstStep];
+            const second = checkpoints[assertion.secondStep];
+            if (first === undefined ||
+                second === undefined ||
+                first.unknown.size > 0 ||
+                second.unknown.size > 0)
+                return result(assertion, 'unresolved', undefined, 'Repeated setup checkpoints are unavailable');
+            return result(assertion, canonicalJson(first.scenario) === canonicalJson(second.scenario) ? 'passed' : 'failed', { firstStep: assertion.firstStep, secondStep: assertion.secondStep });
+        }
+        if (assertion.kind === 'exclusive_flags') {
+            const flags = assertion.scope === 'GLOBAL'
+                ? after.scenario.globalFlags
+                : assertion.scope === 'ROOT'
+                    ? after.scenario.flags
+                    : after.scenario.scopes?.[assertion.scope]?.flags;
+            if (flags === undefined)
+                return result(assertion, 'unresolved', undefined, 'Flag scope is undeclared');
+            const active = assertion.flags.filter((flag) => flags.includes(flag));
+            return result(assertion, active.length <= 1 ? 'passed' : 'failed', active);
+        }
+        const flags = assertion.scope === 'GLOBAL'
+            ? after.scenario.globalFlags
+            : assertion.scope === 'ROOT'
+                ? after.scenario.flags
+                : after.scenario.scopes?.[assertion.scope]?.flags;
+        const targets = assertion.scope === 'ROOT'
+            ? after.scenario.eventTargets
+            : after.scenario.scopes?.[assertion.scope]?.eventTargets;
+        if (flags === undefined && assertion.flags.length > 0)
+            return result(assertion, 'unresolved', undefined, 'Cleanup flag scope is undeclared');
+        const lingeringFlags = assertion.flags.filter((flag) => flags?.includes(flag));
+        const lingeringTargets = assertion.targets.filter((target) => targets?.[target] !== undefined);
+        return result(assertion, lingeringFlags.length === 0 && lingeringTargets.length === 0 ? 'passed' : 'failed', { lingeringFlags, lingeringTargets });
+    });
+}