hoi4-agent-tools 3.0.8 → 3.1.0

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

@@ -1,16 +1,10 @@
+import { registerLegacyTaskTools } from '../server/legacy-task-tools.js';
 import { z } from 'zod/v4';
-import { publicArtifactLink } from '../../core/artifacts.js';
-import { compareCodeUnits } from '../../core/canonical.js';
-import { IdleCacheLifetime } from '../../core/idle-cache-lifetime.js';
-import { emptyServiceResult } from '../../core/result.js';
-import { EventChainViewer, eventDiagnostics, } from '../../event/service.js';
-import { eventDirectionSchema, eventGraphReferenceSchema, eventImpactSubjectSchema, eventInspectModeSchema, eventProposedSourceSchema, eventRenderViewSchema, eventSelectorSchema, eventStateSubjectSchema, } from '../../schemas/event.js';
-import { workspaceIdSchema } from '../../schemas/common.js';
+import { helperExpansionRequestSchema, helperExpansionSummarySchema, } from '../../schemas/helper-expansion.js';
+import { eventDirectionSchema, eventGraphReferenceSchema, eventImpactSubjectSchema, eventInspectModeSchema, eventProposedSourceSchema, eventRenderViewSchema, eventSelectorSchema, eventInspectRequestSchema, eventRenderRequestSchema, eventCompareRequestSchema, validateEventCompareRequest, validateEventInspectRequest, eventStateSubjectSchema, } from '../../schemas/event.js';
 import { compactValidatedInputSchema } from '../server/context-schemas.js';
 import { nonNegativeIntegerSchema, sha256Schema } from '../server/output-schemas.js';
-import { progressReporter } from '../server/progress.js';
-import { errorResult, setInlineFilesScanned, strictOperationResultSchema, toolResult, } from '../server/result.js';
-import { resolveServerWorkspaceId } from '../server/base-tools.js';
+import { strictOperationResultSchema } from '../server/result.js';
 const nestedSelectorSchema = compactValidatedInputSchema(eventSelectorSchema, 'Event selector; see docs/events.md.');
 const nestedStateSubjectSchema = compactValidatedInputSchema(eventStateSubjectSchema, 'State kind and name.');
 const nestedImpactSubjectSchema = compactValidatedInputSchema(eventImpactSubjectSchema, 'Impact kind and name.');
@@ -18,73 +12,31 @@ const nestedGraphReferenceSchema = compactValidatedInputSchema(eventGraphReferen
 const nestedProposedSourceSchema = compactValidatedInputSchema(eventProposedSourceSchema, 'In-memory source overlay; never written.');
 const eventInspectInputSchema = z
     .object({
-    workspaceId: workspaceIdSchema,
-    mode: eventInspectModeSchema,
+    ...eventInspectRequestSchema.shape,
     selector: nestedSelectorSchema.optional(),
     from: nestedSelectorSchema.optional(),
     to: nestedSelectorSchema.optional(),
-    direction: eventDirectionSchema.optional(),
-    maxDepth: z.number().int().min(1).max(64).optional(),
-    maxNodes: z.number().int().min(1).max(5_000).optional(),
-    maxEdges: z.number().int().min(1).max(20_000).optional(),
-    expandHelpers: z.boolean().optional(),
     stateSubject: nestedStateSubjectSchema.optional(),
     impactSubject: nestedImpactSubjectSchema.optional(),
-    refresh: z.boolean().optional(),
+    helperExpansion: compactValidatedInputSchema(helperExpansionRequestSchema, 'Bounded helper paths; opaque continuationUri resumes the same source and roots. See docs/events.md.').optional(),
 })
     .strict()
-    .superRefine((value, context) => {
-    if (value.mode === 'trace' && value.selector === undefined) {
-        context.addIssue({ code: 'custom', path: ['selector'], message: 'Trace requires selector' });
-    }
-    if (value.mode === 'explain_path' && (value.from === undefined || value.to === undefined)) {
-        context.addIssue({
-            code: 'custom',
-            path: value.from === undefined ? ['from'] : ['to'],
-            message: 'Path explanation requires from and to',
-        });
-    }
-    if (value.mode === 'impact' && value.impactSubject === undefined) {
-        context.addIssue({
-            code: 'custom',
-            path: ['impactSubject'],
-            message: 'Impact analysis requires impactSubject',
-        });
-    }
-});
+    .superRefine(validateEventInspectRequest);
 const eventRenderInputSchema = z
     .object({
-    workspaceId: workspaceIdSchema,
-    view: eventRenderViewSchema,
+    ...eventRenderRequestSchema.shape,
     selector: nestedSelectorSchema.optional(),
-    direction: eventDirectionSchema.optional(),
-    maxDepth: z.number().int().min(1).max(64).optional(),
-    maxNodes: z.number().int().min(1).max(240).optional(),
-    expandHelpers: z.boolean().optional(),
-    includeHtml: z.boolean().optional(),
-    refresh: z.boolean().optional(),
 })
     .strict();
 const eventCompareInputSchema = z
     .object({
-    workspaceId: workspaceIdSchema,
+    ...eventCompareRequestSchema.shape,
     before: nestedGraphReferenceSchema.optional(),
     after: nestedGraphReferenceSchema.optional(),
     proposedSources: z.array(nestedProposedSourceSchema).min(1).max(64).optional(),
-    render: z.boolean().optional(),
-    maxRenderNodes: z.number().int().min(1).max(240).optional(),
-    refresh: z.boolean().optional(),
 })
     .strict()
-    .superRefine((value, context) => {
-    if (value.after !== undefined && value.proposedSources !== undefined) {
-        context.addIssue({
-            code: 'custom',
-            path: ['after'],
-            message: 'after and proposedSources are mutually exclusive',
-        });
-    }
-});
+    .superRefine(validateEventCompareRequest);
 const eventGraphCountsSchema = z
     .object({
     events: nonNegativeIntegerSchema,
@@ -128,6 +80,7 @@ const eventInspectOutputSchema = strictOperationResultSchema(z
     revision: sha256Schema,
     graphHash: sha256Schema,
     counts: eventGraphCountsSchema,
+    helperExpansion: helperExpansionSummarySchema.optional(),
     boundary: inspectBoundarySchema,
 })
     .strict());
@@ -206,276 +159,32 @@ const readOnlyEventTool = {
     idempotentHint: true,
     openWorldHint: false,
 };
-function graphCounts(graph, artifacts) {
-    const diagnostics = eventDiagnostics(graph);
-    return {
-        events: graph.statistics.eventCount,
-        options: graph.statistics.optionCount,
-        entries: graph.statistics.entryCount,
-        helpers: graph.statistics.helperCount,
-        unresolvedNodes: graph.statistics.unresolvedNodeCount,
-        terminals: graph.statistics.terminalCount,
-        edges: graph.statistics.edgeCount,
-        derivedEdges: graph.statistics.derivedEdgeCount,
-        stateAccesses: graph.statistics.stateAccessCount,
-        issues: graph.statistics.issueCount,
-        diagnostics: diagnostics.length,
-        blockingDiagnostics: diagnostics.filter(({ severity }) => severity === 'error' || severity === 'blocker').length,
-        skippedSources: graph.skippedSourceCount,
-        artifacts,
-    };
-}
-function graphValidation(graph) {
-    const counts = graphCounts(graph, 0);
-    const focused = graph.analysisMode === 'focused';
-    return {
-        passed: graph.complete && counts.blockingDiagnostics === 0,
-        checks: [
-            {
-                id: 'event-analysis',
-                passed: graph.complete && counts.blockingDiagnostics === 0,
-                message: focused
-                    ? 'Large workspace analysis deferred workspace-wide helper projections and lifecycle passes; direct evidence is linked'
-                    : graph.complete
-                        ? `${counts.blockingDiagnostics} blocking event-chain diagnostics; full evidence is linked`
-                        : `${graph.skippedSourceCount} event-analysis source(s) were skipped; full evidence is linked`,
-            },
-        ],
-    };
-}
-function inspectRequest(input, context, signal) {
-    return {
-        workspaceId: input.workspaceId,
-        mode: input.mode,
-        ...(input.selector === undefined
-            ? {}
-            : { selector: input.selector }),
-        ...(input.from === undefined
-            ? {}
-            : { from: input.from }),
-        ...(input.to === undefined ? {} : { to: input.to }),
-        ...(input.direction === undefined ? {} : { direction: input.direction }),
-        ...(input.maxDepth === undefined ? {} : { maxDepth: input.maxDepth }),
-        ...(input.maxNodes === undefined ? {} : { maxNodes: input.maxNodes }),
-        ...(input.maxEdges === undefined ? {} : { maxEdges: input.maxEdges }),
-        ...(input.expandHelpers === undefined ? {} : { expandHelpers: input.expandHelpers }),
-        ...(input.stateSubject === undefined ? {} : { stateSubject: input.stateSubject }),
-        ...(input.impactSubject === undefined ? {} : { impactSubject: input.impactSubject }),
-        ...(input.refresh === undefined ? {} : { refresh: input.refresh }),
-        ...(context.principal === undefined ? {} : { principal: context.principal }),
-        signal,
-    };
-}
-function renderRequest(input, context, signal) {
-    return {
-        workspaceId: input.workspaceId,
-        view: input.view,
-        ...(input.selector === undefined
-            ? {}
-            : { selector: input.selector }),
-        ...(input.direction === undefined ? {} : { direction: input.direction }),
-        ...(input.maxDepth === undefined ? {} : { maxDepth: input.maxDepth }),
-        ...(input.maxNodes === undefined ? {} : { maxNodes: input.maxNodes }),
-        ...(input.expandHelpers === undefined ? {} : { expandHelpers: input.expandHelpers }),
-        ...(input.includeHtml === undefined ? {} : { includeHtml: input.includeHtml }),
-        ...(input.refresh === undefined ? {} : { refresh: input.refresh }),
-        ...(context.principal === undefined ? {} : { principal: context.principal }),
-        signal,
-    };
-}
-function compareRequest(input, context, signal) {
-    return {
-        workspaceId: input.workspaceId,
-        ...(input.before === undefined
-            ? {}
-            : { before: input.before }),
-        ...(input.after === undefined
-            ? {}
-            : { after: input.after }),
-        ...(input.proposedSources === undefined
-            ? {}
-            : {
-                proposedSources: input.proposedSources,
-            }),
-        ...(input.render === undefined ? {} : { render: input.render }),
-        ...(input.maxRenderNodes === undefined ? {} : { maxRenderNodes: input.maxRenderNodes }),
-        ...(input.refresh === undefined ? {} : { refresh: input.refresh }),
-        ...(context.principal === undefined ? {} : { principal: context.principal }),
-        signal,
-    };
-}
-export function registerEventTools(server, engine, context) {
-    const viewer = new EventChainViewer(engine);
-    const cacheLifetime = new IdleCacheLifetime(() => viewer.clearCaches());
-    server.registerTool('hoi4.event_inspect', {
+export const eventTaskTools = [
+    {
+        name: 'hoi4.event_inspect',
         title: 'Inspect event chains',
         description: 'Scan, find roots, trace, explain paths, inspect state flow, lint, or assess impact. Full source-linked reports are resources.',
         inputSchema: eventInspectInputSchema,
         outputSchema: eventInspectOutputSchema,
         annotations: readOnlyEventTool,
-    }, async (input, extra) => {
-        const workspaceId = await resolveServerWorkspaceId(engine, context, input.workspaceId, extra.signal);
-        const releaseCaches = cacheLifetime.begin();
-        try {
-            const progress = progressReporter(extra);
-            await progress.report(0, 3, 'Analyzing event chain');
-            const inspected = await viewer.inspect(inspectRequest({ ...input, workspaceId }, context, progress.signal));
-            await progress.report(2, 3, 'Linking complete event analysis');
-            const result = emptyServiceResult(workspaceId, {
-                mode: inspected.mode,
-                analysisMode: inspected.graph.analysisMode ?? 'full',
-                revision: inspected.graph.revision,
-                graphHash: inspected.graphHash,
-                counts: graphCounts(inspected.graph, inspected.artifacts.length),
-                boundary: {
-                    direction: input.direction ?? 'both',
-                    maxDepth: input.maxDepth ?? 8,
-                    maxNodes: input.maxNodes ?? 500,
-                    maxEdges: input.maxEdges ?? 2_000,
-                    expandHelpers: input.expandHelpers ?? (input.mode === 'explain_path' ? true : false),
-                    refresh: input.refresh ?? input.mode === 'scan',
-                },
-            });
-            result.code = inspected.graph.complete ? 'EVENT_INSPECTED' : 'EVENT_INSPECTED_PARTIAL';
-            setInlineFilesScanned(result, inspected.graph.filesScanned);
-            result.artifacts = inspected.artifacts.map(publicArtifactLink);
-            result.validation = graphValidation(inspected.graph);
-            await progress.report(3, 3, 'Event inspection complete');
-            return toolResult(result);
-        }
-        catch (error) {
-            return errorResult(error, workspaceId);
-        }
-        finally {
-            releaseCaches();
-        }
-    });
-    server.registerTool('hoi4.event_render', {
+    },
+    {
+        name: 'hoi4.event_render',
         title: 'Render event chains',
         description: 'Render deterministic JSON, SVG, PNG, and optional HTML for an event-chain view. Complete artifacts retain source links.',
         inputSchema: eventRenderInputSchema,
         outputSchema: eventRenderOutputSchema,
         annotations: readOnlyEventTool,
-    }, async (input, extra) => {
-        const workspaceId = await resolveServerWorkspaceId(engine, context, input.workspaceId, extra.signal);
-        const releaseCaches = cacheLifetime.begin();
-        try {
-            const progress = progressReporter(extra);
-            await progress.report(0, 3, 'Rendering event-chain view');
-            const rendered = await viewer.renderAndStore(renderRequest({ ...input, workspaceId }, context, progress.signal));
-            await progress.report(2, 3, 'Linking complete event renders');
-            const result = emptyServiceResult(workspaceId, {
-                view: rendered.render.view,
-                analysisMode: rendered.graph.analysisMode ?? 'full',
-                revision: rendered.graph.revision,
-                graphHash: rendered.graphHash,
-                layoutHash: rendered.render.layout.layoutHash,
-                hashes: rendered.render.hashes,
-                counts: {
-                    ...graphCounts(rendered.graph, rendered.artifacts.length),
-                    selectedNodes: rendered.render.selectedNodeIds.length,
-                    omittedNodes: rendered.render.omittedNodeCount,
-                    branchRenders: rendered.branches.length,
-                },
-                boundary: {
-                    direction: input.direction ?? 'both',
-                    maxDepth: input.maxDepth ?? 4,
-                    maxNodes: input.maxNodes ?? 120,
-                    expandHelpers: input.expandHelpers ?? false,
-                    includeHtml: input.includeHtml ?? false,
-                    refresh: input.refresh ?? false,
-                },
-            });
-            result.code = rendered.graph.complete ? 'EVENT_RENDERED' : 'EVENT_RENDERED_PARTIAL';
-            setInlineFilesScanned(result, rendered.graph.filesScanned);
-            result.artifacts = rendered.artifacts.map(publicArtifactLink);
-            result.validation = graphValidation(rendered.graph);
-            await progress.report(3, 3, 'Event render complete');
-            return toolResult(result);
-        }
-        catch (error) {
-            return errorResult(error, workspaceId);
-        }
-        finally {
-            releaseCaches();
-        }
-    });
-    server.registerTool('hoi4.event_compare', {
+    },
+    {
+        name: 'hoi4.event_compare',
         title: 'Compare event chains',
         description: 'Compare cached, artifact-backed, current, or in-memory proposed event graphs without writing source. Full changes are resources.',
         inputSchema: eventCompareInputSchema,
         outputSchema: eventCompareOutputSchema,
         annotations: readOnlyEventTool,
-    }, async (input, extra) => {
-        const workspaceId = await resolveServerWorkspaceId(engine, context, input.workspaceId, extra.signal);
-        const releaseCaches = cacheLifetime.begin();
-        try {
-            const progress = progressReporter(extra);
-            await progress.report(0, 3, 'Comparing event-chain graphs');
-            const compared = await viewer.compareAndStore(compareRequest({ ...input, workspaceId }, context, progress.signal));
-            await progress.report(2, 3, 'Linking complete event comparison');
-            const { comparison } = compared;
-            const result = emptyServiceResult(workspaceId, {
-                beforeRevision: comparison.beforeRevision,
-                afterRevision: comparison.afterRevision,
-                beforeGraphHash: comparison.beforeGraphHash,
-                afterGraphHash: comparison.afterGraphHash,
-                ...(compared.render === undefined ? {} : { renderHashes: compared.render.hashes }),
-                counts: {
-                    changes: comparison.changes.length,
-                    addedNodes: comparison.addedNodeIds.length,
-                    removedNodes: comparison.removedNodeIds.length,
-                    changedNodes: comparison.changedNodeIds.length,
-                    addedEdges: comparison.addedEdgeIds.length,
-                    removedEdges: comparison.removedEdgeIds.length,
-                    changedEdges: comparison.changedEdgeIds.length,
-                    addedStateAccesses: comparison.addedStateAccessIds.length,
-                    removedStateAccesses: comparison.removedStateAccessIds.length,
-                    changedStateAccesses: comparison.changedStateAccessIds.length,
-                    addedStateLinks: comparison.addedStateLinkIds.length,
-                    removedStateLinks: comparison.removedStateLinkIds.length,
-                    changedStateLinks: comparison.changedStateLinkIds.length,
-                    addedDiagnostics: comparison.addedIssueIds.length,
-                    resolvedDiagnostics: comparison.resolvedIssueIds.length,
-                    addedUnresolved: comparison.addedUnresolvedIds.length,
-                    resolvedUnresolved: comparison.resolvedUnresolvedIds.length,
-                    disconnectedRoots: comparison.newlyDisconnectedRootIds.length,
-                    disconnectedBranches: comparison.newlyDisconnectedBranchIds.length,
-                    disconnectedTerminals: comparison.newlyDisconnectedTerminalIds.length,
-                    beforeSkippedSources: compared.before.skippedSourceCount,
-                    afterSkippedSources: compared.after.skippedSourceCount,
-                    artifacts: compared.artifacts.length,
-                },
-                boundary: {
-                    proposedSources: input.proposedSources?.length ?? 0,
-                    render: input.render ?? true,
-                    maxRenderNodes: input.maxRenderNodes ?? 120,
-                    refresh: compared.refresh,
-                },
-            });
-            result.code =
-                compared.before.complete && compared.after.complete
-                    ? 'EVENT_COMPARED'
-                    : 'EVENT_COMPARED_PARTIAL';
-            setInlineFilesScanned(result, [...new Set([...compared.before.filesScanned, ...compared.after.filesScanned])].sort(compareCodeUnits));
-            result.artifacts = compared.artifacts.map(publicArtifactLink);
-            const beforeValidation = graphValidation(compared.before);
-            const afterValidation = graphValidation(compared.after);
-            result.validation = {
-                passed: beforeValidation.passed && afterValidation.passed,
-                checks: [...beforeValidation.checks, ...afterValidation.checks].map((check, index) => ({
-                    ...check,
-                    id: `${index === 0 ? 'before' : 'after'}-${check.id}`,
-                })),
-            };
-            await progress.report(3, 3, 'Event comparison complete');
-            return toolResult(result);
-        }
-        catch (error) {
-            return errorResult(error, workspaceId);
-        }
-        finally {
-            releaseCaches();
-        }
-    });
+    },
+];
+export function registerEventTools(server) {
+    registerLegacyTaskTools(server, eventTaskTools);
 }