hoi4-agent-tools 3.0.9 → 3.2.0

package/dist/hoi4_agent_tools/mcp/transports/negotiated-stdio.js

@@ -0,0 +1,121 @@
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
+import { createMcpServer } from '../server/create.js';
+import { createModernOperationServer } from '../server/create-modern-operations.js';
+import { BoundedStdioServerTransport, STDIO_MAX_FRAME_BYTES } from './bounded-stdio.js';
+import { FinalProtocolTransport } from './protocol-gate.js';
+const MAX_QUEUED_MESSAGES = 128;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Modern discovery or metadata selects the modern connection; initialize selects legacy. */
+export function isModernStdioOpening(message) {
+    if (!('method' in message))
+        return false;
+    if (message.method === 'server/discover')
+        return true;
+    if (message.method === 'initialize' || !('params' in message))
+        return false;
+    const params = message.params;
+    const meta = isRecord(params) ? params._meta : undefined;
+    return (isRecord(meta) && Object.keys(meta).some((key) => key.startsWith('io.modelcontextprotocol/')));
+}
+/** One logical SDK connection over the already-started bounded physical stream. */
+class PinnedStdioTransport {
+    physical;
+    reportError;
+    onclose = () => undefined;
+    onerror = () => undefined;
+    onmessage = () => undefined;
+    started = false;
+    queuedBytes = 0;
+    queue = [];
+    constructor(physical, reportError) {
+        this.physical = physical;
+        this.reportError = reportError;
+    }
+    receive(message) {
+        if (this.started) {
+            this.onmessage(message);
+            return;
+        }
+        const bytes = Buffer.byteLength(JSON.stringify(message)) + 1;
+        if (this.queue.length >= MAX_QUEUED_MESSAGES ||
+            bytes > STDIO_MAX_FRAME_BYTES - this.queuedBytes) {
+            const error = new Error('Stdio negotiation queue exceeded its bounded limit');
+            this.reportError(error);
+            this.onerror(error);
+            void this.physical.close();
+            return;
+        }
+        this.queue.push(message);
+        this.queuedBytes += bytes;
+    }
+    start() {
+        if (this.started)
+            throw new Error('Negotiated stdio transport already started');
+        this.started = true;
+        for (const message of this.queue.splice(0))
+            this.onmessage(message);
+        this.queuedBytes = 0;
+        return Promise.resolve();
+    }
+    send(message) {
+        return this.physical.send(message);
+    }
+    close() {
+        return this.physical.close();
+    }
+}
+/** Pin the protocol generation on the first message while retaining the old bounded wire. */
+export async function serveNegotiatedStdio(engine, options) {
+    const physical = new BoundedStdioServerTransport({
+        ...(options.stdin === undefined ? {} : { stdin: options.stdin }),
+        ...(options.stdout === undefined ? {} : { stdout: options.stdout }),
+    });
+    let pinned;
+    const reportedErrors = new WeakSet();
+    const reportError = (error) => {
+        if (reportedErrors.has(error))
+            return;
+        reportedErrors.add(error);
+        options.onerror(error);
+    };
+    physical.onclose = () => pinned?.onclose();
+    physical.onerror = (error) => {
+        reportError(error);
+        pinned?.onerror(error);
+    };
+    physical.onmessage = (message) => {
+        if (pinned === undefined) {
+            pinned = new PinnedStdioTransport(physical, reportError);
+            try {
+                if (isModernStdioOpening(message)) {
+                    serveStdio(() => createModernOperationServer(engine, {}, undefined, options.createModernPrivateTools === undefined
+                        ? {}
+                        : { createPrivateTools: options.createModernPrivateTools }), {
+                        transport: pinned,
+                        legacy: 'reject',
+                        onerror: reportError,
+                    });
+                }
+                else {
+                    const server = createMcpServer(engine, {});
+                    options.registerLegacy?.(server);
+                    server.server.onerror = reportError;
+                    void server.connect(new FinalProtocolTransport(pinned)).catch((error) => {
+                        options.onFailure(error);
+                        void physical.close();
+                    });
+                }
+            }
+            catch (error) {
+                options.onFailure(error);
+                void physical.close();
+                return;
+            }
+        }
+        pinned.receive(message);
+    };
+    await physical.start();
+    return physical;
+}

package/dist/hoi4_agent_tools/probability/job-operations.js

@@ -0,0 +1,58 @@
+import { z } from 'zod/v4';
+import { IdleCacheLifetime } from '../core/idle-cache-lifetime.js';
+import { errorResult, toolResult } from '../core/operation-result.js';
+import { ServiceError } from '../core/result.js';
+import { probabilityCompareRequestSchema, probabilityEvaluateRequestSchema, probabilityInspectRequestSchema, probabilityRenderRequestSchema, probabilitySequenceRequestSchema, probabilitySimulateRequestSchema, probabilitySweepRequestSchema, } from '../schemas/probability-requests.js';
+import { compareProbabilities, evaluateProbabilities, inspectProbabilities, normalizeProbabilityCompareRequest, normalizeProbabilityEvaluateRequest, normalizeProbabilityInspectRequest, normalizeProbabilityRenderRequest, normalizeProbabilitySequenceRequest, normalizeProbabilitySimulateRequest, normalizeProbabilitySweepRequest, renderProbabilities, sequenceProbabilities, simulateProbabilities, sweepProbabilities, } from './operations.js';
+import { ProbabilityAnalyzer } from './service.js';
+const wireResult = z.record(z.string(), z.json());
+/** Registers probability operations without invoking transport handlers. */
+export function registerProbabilityJobs(operations, engine) {
+    const analyzer = new ProbabilityAnalyzer(engine);
+    const lifetime = new IdleCacheLifetime(() => analyzer.clearCaches());
+    function register(name, schema, normalize, execute, message) {
+        operations.registerRead(name, schema, async (input, context) => {
+            const release = lifetime.begin();
+            try {
+                if (input.workspaceId !== 'current' && input.workspaceId !== context.workspaceId)
+                    throw new ServiceError('JOB_ARGUMENT_SCOPE_MISMATCH', 'The request workspace does not match the authorized job workspace');
+                await context.progress({ completed: 0, total: 3, message });
+                const result = await execute(analyzer, normalize(input), {
+                    workspaceId: context.workspaceId,
+                    ...(context.principal === undefined ? {} : { principal: context.principal }),
+                    signal: context.signal,
+                });
+                await context.progress({
+                    completed: 3,
+                    total: 3,
+                    message: 'Probability operation complete',
+                });
+                const wire = wireResult.parse(JSON.parse(JSON.stringify(toolResult(result))));
+                const revision = result.data !== null &&
+                    typeof result.data === 'object' &&
+                    'sourceRevision' in result.data &&
+                    typeof result.data.sourceRevision === 'string'
+                    ? result.data.sourceRevision
+                    : undefined;
+                if (revision !== undefined)
+                    await context.stageResult(wire, { sourceRevision: revision });
+                return wire;
+            }
+            catch (error) {
+                if (context.signal.aborted)
+                    throw error;
+                return wireResult.parse(JSON.parse(JSON.stringify(errorResult(error, context.workspaceId))));
+            }
+            finally {
+                release();
+            }
+        });
+    }
+    register('hoi4.probability_inspect', probabilityInspectRequestSchema, normalizeProbabilityInspectRequest, inspectProbabilities, 'Inspecting weighted source');
+    register('hoi4.probability_evaluate', probabilityEvaluateRequestSchema, normalizeProbabilityEvaluateRequest, evaluateProbabilities, 'Evaluating weighted scenarios');
+    register('hoi4.probability_sweep', probabilitySweepRequestSchema, normalizeProbabilitySweepRequest, sweepProbabilities, 'Evaluating parameter sweep');
+    register('hoi4.probability_simulate', probabilitySimulateRequestSchema, normalizeProbabilitySimulateRequest, simulateProbabilities, 'Sampling uncertain scenarios');
+    register('hoi4.probability_sequence', probabilitySequenceRequestSchema, normalizeProbabilitySequenceRequest, sequenceProbabilities, 'Analyzing declared sequence');
+    register('hoi4.probability_compare', probabilityCompareRequestSchema, normalizeProbabilityCompareRequest, compareProbabilities, 'Comparing weighted source');
+    register('hoi4.probability_render', probabilityRenderRequestSchema, normalizeProbabilityRenderRequest, renderProbabilities, 'Rendering analysis resources');
+}

package/dist/hoi4_agent_tools/probability/operations.js

@@ -0,0 +1,183 @@
+import { emptyServiceResult } from '../core/result.js';
+import { setInlineFilesScanned } from '../core/operation-result.js';
+import { probabilityCompareRequestSchema, probabilityEvaluateRequestSchema, probabilityInspectRequestSchema, probabilityRenderRequestSchema, probabilitySequenceRequestSchema, probabilitySimulateRequestSchema, probabilitySweepRequestSchema, } from '../schemas/probability-requests.js';
+function runtime(context, refresh) {
+    return {
+        workspaceId: context.workspaceId,
+        ...(context.principal === undefined ? {} : { principal: context.principal }),
+        ...(context.signal === undefined ? {} : { signal: context.signal }),
+        ...(refresh === undefined ? {} : { refresh }),
+    };
+}
+export function probabilityAnalysisData(result) {
+    return {
+        operation: result.operation,
+        analysisId: result.analysisId,
+        analysisStatus: result.status,
+        adapterId: result.adapter.id,
+        sourceRevision: result.metadata.sourceRevision,
+        sourceHash: result.metadata.sourceHash,
+        scenarioHash: result.metadata.scenarioHash,
+        cacheKey: result.metadata.cacheKey,
+        scenarios: result.scenarios.length,
+        candidates: result.scenarios.reduce((sum, scenario) => sum + scenario.candidates.length, 0),
+        ...(result.scenarios.some(({ scopePools }) => (scopePools?.length ?? 0) > 0)
+            ? {
+                scopePools: result.scenarios.reduce((sum, scenario) => sum + (scenario.scopePools?.length ?? 0), 0),
+                scopePoolCandidates: result.scenarios.reduce((sum, scenario) => sum +
+                    (scenario.scopePools?.reduce((poolSum, pool) => poolSum + pool.candidates.length, 0) ?? 0), 0),
+            }
+            : {}),
+        unresolved: result.unresolved.length,
+        diagnostics: result.diagnostics.length,
+        ...(result.sweep === undefined ? {} : { sweepPoints: result.sweep.points.length }),
+        ...(result.metadata.samples === undefined ? {} : { samples: result.metadata.samples }),
+        ...(result.sequence === undefined ? {} : { sequenceMethod: result.sequence.method }),
+        ...(result.comparison === undefined
+            ? {}
+            : { comparisonChanges: result.comparison.scenarioChanges.length }),
+        visualResources: result.resources.filter(({ mimeType }) => mimeType.startsWith('image/'))
+            .length,
+    };
+}
+export function probabilityAnalysisServiceResult(workspaceId, result) {
+    const output = emptyServiceResult(workspaceId, probabilityAnalysisData(result));
+    output.code =
+        result.status === 'complete'
+            ? 'PROBABILITY_ANALYZED'
+            : result.status === 'stale'
+                ? result.diagnostics.some(({ code }) => code === 'PROBABILITY_SCENARIO_STALE')
+                    ? 'PROBABILITY_SCENARIO_STALE'
+                    : 'PROBABILITY_ANALYSIS_STALE'
+                : 'PROBABILITY_ANALYZED_PARTIAL';
+    output.artifacts = result.resources;
+    output.diagnostics = result.diagnostics;
+    output.validation = {
+        passed: result.status !== 'blocked' && result.status !== 'cancelled',
+        checks: [
+            {
+                id: 'uncertainty-visible',
+                passed: true,
+                message: `${result.unresolved.length} unresolved or bounded analysis item(s) are explicit`,
+            },
+        ],
+    };
+    return output;
+}
+export function normalizeProbabilityInspectRequest(input) {
+    return probabilityInspectRequestSchema.parse(input);
+}
+export function normalizeProbabilityEvaluateRequest(input) {
+    return probabilityEvaluateRequestSchema.parse(input);
+}
+export function normalizeProbabilitySweepRequest(input) {
+    return probabilitySweepRequestSchema.parse(input);
+}
+export function normalizeProbabilitySimulateRequest(input) {
+    return probabilitySimulateRequestSchema.parse(input);
+}
+export function normalizeProbabilitySequenceRequest(input) {
+    return probabilitySequenceRequestSchema.parse(input);
+}
+export function normalizeProbabilityCompareRequest(input) {
+    return probabilityCompareRequestSchema.parse(input);
+}
+export function normalizeProbabilityRenderRequest(input) {
+    return probabilityRenderRequestSchema.parse(input);
+}
+export async function inspectProbabilities(analyzer, input, context) {
+    const inspected = await analyzer.inspect(runtime(context, input.refresh), input.adapter, input.source, input.candidatePool, input.customPoolManifest);
+    const result = emptyServiceResult(context.workspaceId, {
+        adapters: inspected.adapters.length,
+        ...(inspected.surface === undefined
+            ? {}
+            : {
+                adapterId: inspected.surface.adapter.id,
+                sourceRevision: inspected.surface.sourceRevision,
+                sourceHash: inspected.surface.sourceHash,
+                poolComplete: inspected.surface.poolComplete,
+            }),
+        ...(inspected.discovery === undefined
+            ? {}
+            : {
+                ...(inspected.discovery.requestedAdapter === undefined
+                    ? {}
+                    : { requestedAdapter: inspected.discovery.requestedAdapter }),
+                ...(inspected.discovery.suggestedAdapter === undefined
+                    ? {}
+                    : { suggestedAdapter: inspected.discovery.suggestedAdapter }),
+                discoveryReason: inspected.discovery.reason,
+                sourceRevision: inspected.discovery.sourceRevision,
+                sourceHash: inspected.discovery.sourceHash,
+            }),
+        candidates: inspected.surface?.candidateCount ?? 0,
+        availableCandidates: inspected.discovery?.availableAdapters.reduce((sum, { candidateCount }) => sum + candidateCount, 0) ?? 0,
+        availableAdapters: inspected.discovery?.availableAdapters.map((available) => ({
+            adapterId: available.adapterId,
+            candidates: available.candidateCount,
+            identifierMatches: available.identifierMatchCount,
+            candidatePoolMatches: available.candidatePoolMatchCount,
+        })) ?? [],
+        candidateExamples: inspected.discovery?.exampleCandidateIds ?? [],
+        requiredInputs: inspected.surface?.requiredInputs.length ?? 0,
+        unresolved: inspected.surface?.unsupported.length ?? 0,
+    });
+    result.code =
+        inspected.surface !== undefined
+            ? 'PROBABILITY_SOURCE_INSPECTED'
+            : inspected.discovery !== undefined
+                ? 'PROBABILITY_SOURCE_DISCOVERED'
+                : 'PROBABILITY_ADAPTERS_LISTED';
+    result.artifacts = inspected.artifacts;
+    setInlineFilesScanned(result, inspected.filesScanned);
+    return result;
+}
+export async function evaluateProbabilities(analyzer, input, context) {
+    const analyzed = await analyzer.evaluate({
+        ...runtime(context, input.refresh),
+        ...input,
+        workspaceId: context.workspaceId,
+    });
+    return probabilityAnalysisServiceResult(context.workspaceId, analyzed);
+}
+export async function sweepProbabilities(analyzer, input, context) {
+    const analyzed = await analyzer.sweep({
+        ...runtime(context, input.refresh),
+        ...input,
+        workspaceId: context.workspaceId,
+    });
+    return probabilityAnalysisServiceResult(context.workspaceId, analyzed);
+}
+export async function simulateProbabilities(analyzer, input, context) {
+    const analyzed = await analyzer.simulate({
+        ...runtime(context, input.refresh),
+        ...input,
+        workspaceId: context.workspaceId,
+    });
+    return probabilityAnalysisServiceResult(context.workspaceId, analyzed);
+}
+export async function sequenceProbabilities(analyzer, input, context) {
+    const analyzed = await analyzer.sequence({
+        ...runtime(context),
+        ...input,
+        workspaceId: context.workspaceId,
+    });
+    return probabilityAnalysisServiceResult(context.workspaceId, analyzed);
+}
+export async function compareProbabilities(analyzer, input, context) {
+    const analyzed = await analyzer.compare({
+        ...runtime(context, input.refresh),
+        ...input,
+        workspaceId: context.workspaceId,
+    });
+    return probabilityAnalysisServiceResult(context.workspaceId, analyzed);
+}
+export async function renderProbabilities(analyzer, input, context) {
+    const analyzed = await analyzer.render({
+        ...runtime(context),
+        ...input,
+        workspaceId: context.workspaceId,
+        outputs: input.outputs.filter((output) => output !== 'json'),
+    });
+    return probabilityAnalysisServiceResult(context.workspaceId, analyzed);
+}

package/dist/hoi4_agent_tools/probability/service.js

@@ -6,6 +6,7 @@ import { probabilityDomainScanPatterns, probabilitySharedDefinitionPatterns, } f
 import { publicArtifactLink } from '../core/artifacts.js';
 import { ServiceError } from '../core/result.js';
 import { PACKAGE_VERSION } from '../version.js';
+import { probabilityAnalysisResultSchema } from '../schemas/probability.js';
 import { probabilityAdapter, probabilityAdapters } from './adapters.js';
 import { compareProbabilityResults } from './compare.js';
 import { evaluateExactCandidates, evaluateSurfaceScenarios } from './evaluation.js';
@@ -710,6 +711,28 @@ export class ProbabilityAnalyzer {
         this.state.byCacheKey.clear();
         this.engine.releaseScanCaches();
     }
+    async retainedAnalysis(request) {
+        const workspace = this.engine.resolver.get(request.workspaceId, request.principal);
+        const candidates = (await this.engine.artifacts.list(workspace, request.signal)).filter(({ name }) => name === `${request.analysisId}.json`);
+        for (const artifact of candidates) {
+            request.signal?.throwIfAborted();
+            try {
+                const logical = await this.engine.artifacts.readLogical(workspace, artifact.uri, { mimeType: 'application/json', maxBytes: 134_217_728, maxChunks: 2_048 }, request.signal);
+                const result = probabilityAnalysisResultSchema.parse(JSON.parse(logical.bytes.toString('utf8')));
+                if (result.analysisId !== request.analysisId ||
+                    result.metadata.workspaceId !== request.workspaceId ||
+                    result.operation === 'render')
+                    continue;
+                rememberAnalysis(this.state, result);
+                return result;
+            }
+            catch (error) {
+                if (error instanceof ServiceError && error.code === 'ARTIFACT_WORKSPACE_MISMATCH')
+                    throw error;
+            }
+        }
+        throw new ServiceError('PROBABILITY_ANALYSIS_NOT_CACHED', 'Render requires a retained analysis ID from this authorized workspace', { analysisId: request.analysisId });
+    }
     async scan(context, sourcePaths = [], emptyScope = 'domain') {
         if (context.refresh === true)
             this.engine.invalidate(context.workspaceId);
@@ -1394,9 +1417,7 @@ export class ProbabilityAnalyzer {
         return this.store(result, request.outputs ?? ['json', 'comparison'], false, request.signal, request.principal);
     }
     async render(request) {
-        const result = this.state.byId.get(request.analysisId);
-        if (result === undefined)
-            throw new ServiceError('PROBABILITY_ANALYSIS_NOT_CACHED', 'Render requires an analysis ID produced by this server process', { analysisId: request.analysisId });
+        const result = this.state.byId.get(request.analysisId) ?? (await this.retainedAnalysis(request));
         if (result.metadata.workspaceId !== request.workspaceId)
             throw new ServiceError('PROBABILITY_ANALYSIS_WORKSPACE_MISMATCH', 'Analysis belongs to a different workspace');
         if (request.expectedScenarioHash !== undefined &&

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();

package/dist/hoi4_agent_tools/schemas/common.js

@@ -4,6 +4,8 @@ export const workspaceIdSchema = z
     .string()
     .regex(/^[a-z][a-z0-9_-]{0,63}$/u)
     .default('current');
+/** Caller-stable deduplication key for resumable background mutations. */
+export const backgroundRequestKeySchema = z.string().min(1).max(256);
 const diagnosticCodeSchema = z.string().min(1).max(256);
 const diagnosticMessageSchema = z.string().max(4096);
 const sourceDisplayPathSchema = z.string().min(1).max(4096);