hoi4-agent-tools 3.0.9 → 3.1.0

package/dist/hoi4_agent_tools/technology/operations.js

@@ -0,0 +1,125 @@
+import { publicArtifactLink } from '../core/artifacts.js';
+import { helperExpansionValidation } from '../core/helper-expansion.js';
+import { compareCodeUnits, hashCanonical } from '../core/canonical.js';
+import { emptyServiceResult } from '../core/result.js';
+import { setInlineFilesScanned } from '../core/operation-result.js';
+import { technologyCompareRequestSchema, technologyInspectRequestSchema, technologyRenderRequestSchema, } from '../schemas/technology.js';
+import { technologyDiagnostics } from './service.js';
+export function normalizeTechnologyInspectionRequest(input) {
+    return JSON.parse(JSON.stringify(technologyInspectRequestSchema.parse(input)));
+}
+export function normalizeTechnologyRenderRequest(input) {
+    return JSON.parse(JSON.stringify(technologyRenderRequestSchema.parse(input)));
+}
+export function normalizeTechnologyCompareRequest(input) {
+    return JSON.parse(JSON.stringify(technologyCompareRequestSchema.parse(input)));
+}
+export function technologyGraphHash(graph) {
+    return hashCanonical({
+        schemaVersion: graph.schemaVersion,
+        analysisMode: graph.analysisMode ?? 'full',
+        workspaceIdentity: graph.workspaceIdentity,
+        revision: graph.revision,
+        statistics: graph.statistics,
+        sourceHashes: graph.sourceHashes,
+    });
+}
+export function technologyCounts(graph, artifacts) {
+    return {
+        technologies: graph.statistics.technologyCount,
+        legacyDoctrines: graph.statistics.legacyDoctrineCount,
+        folders: graph.statistics.folderCount,
+        placements: graph.statistics.placementCount,
+        edges: graph.edges.length,
+        unlocks: graph.statistics.unlockCount,
+        references: graph.statistics.externalReferenceCount,
+        issues: graph.statistics.issueCount,
+        unresolved: graph.statistics.unresolvedCount,
+        artifacts,
+    };
+}
+export function technologyValidation(graph) {
+    const blocking = technologyDiagnostics(graph).filter(({ severity }) => severity === 'error' || severity === 'blocker').length;
+    return {
+        passed: graph.complete && blocking === 0,
+        checks: [
+            {
+                id: 'technology-analysis',
+                passed: graph.complete && blocking === 0,
+                message: graph.complete
+                    ? `${blocking} blocking technology diagnostics; full evidence is linked`
+                    : graph.analysisMode === 'focused'
+                        ? 'Helper projections were deferred for this large workspace; direct evidence is linked'
+                        : graph.unresolved.some(({ blockers }) => blockers.some(({ code }) => code === 'TECH_HELPER_DEPTH_BLOCKED' ||
+                            code === 'TECH_HELPER_PROJECTION_LIMIT'))
+                            ? 'Helper expansion reached a depth or materialization boundary; helper_expansion mode provides bounded source-linked continuation'
+                            : `${graph.skippedSourceCount} source(s) were skipped; full evidence is linked`,
+            },
+        ],
+    };
+}
+export async function inspectTechnologies(viewer, input) {
+    const output = await viewer.analyze(input);
+    const result = emptyServiceResult(input.workspaceId, {
+        mode: input.mode,
+        revision: output.graph.revision,
+        graphHash: technologyGraphHash(output.graph),
+        counts: technologyCounts(output.graph, output.artifacts.length),
+        ...(output.helperExpansion === undefined ? {} : { helperExpansion: output.helperExpansion }),
+    });
+    result.code =
+        (output.helperExpansion?.complete ?? output.graph.complete)
+            ? 'TECH_INSPECTED'
+            : 'TECH_INSPECTED_PARTIAL';
+    setInlineFilesScanned(result, output.graph.filesScanned);
+    result.artifacts = output.artifacts.map(publicArtifactLink);
+    result.validation = technologyValidation(output.graph);
+    if (output.helperExpansion !== undefined)
+        result.validation = helperExpansionValidation(output.helperExpansion);
+    return result;
+}
+export async function renderTechnologies(viewer, input) {
+    const output = await viewer.renderAndStore(input);
+    const result = emptyServiceResult(input.workspaceId, {
+        view: output.render.view,
+        revision: output.graph.revision,
+        graphHash: technologyGraphHash(output.graph),
+        hashes: output.render.hashes,
+        selectedNodes: output.render.selectedIds.length,
+        omittedNodes: output.render.omittedNodeCount,
+        focusedRenders: output.focused.length,
+        sourceAccurate: output.render.sourceAccurate,
+    });
+    result.code = output.graph.complete ? 'TECH_RENDERED' : 'TECH_RENDERED_PARTIAL';
+    setInlineFilesScanned(result, output.graph.filesScanned);
+    result.artifacts = output.artifacts.map(publicArtifactLink);
+    result.validation = technologyValidation(output.graph);
+    return result;
+}
+export async function compareTechnologies(viewer, input) {
+    const output = await viewer.compareAndStore(input);
+    const comparison = output.comparison;
+    const result = emptyServiceResult(input.workspaceId, {
+        beforeRevision: comparison.beforeRevision,
+        afterRevision: comparison.afterRevision,
+        added: comparison.technologies.added.length,
+        removed: comparison.technologies.removed.length,
+        renamed: comparison.technologies.renamed.length,
+        moved: comparison.technologies.moved.length,
+        regressions: comparison.regressions.length,
+        artifacts: output.artifacts.length,
+        ...(output.render === undefined ? {} : { renderHashes: output.render.hashes }),
+    });
+    result.code =
+        output.before.complete && output.after.complete ? 'TECH_COMPARED' : 'TECH_COMPARED_PARTIAL';
+    setInlineFilesScanned(result, [...new Set([...output.before.filesScanned, ...output.after.filesScanned])].sort(compareCodeUnits));
+    result.artifacts = output.artifacts.map(publicArtifactLink);
+    result.validation = {
+        passed: technologyValidation(output.before).passed && technologyValidation(output.after).passed,
+        checks: [
+            ...technologyValidation(output.before).checks,
+            ...technologyValidation(output.after).checks,
+        ],
+    };
+    return result;
+}

package/dist/hoi4_agent_tools/technology/service.js

@@ -1,4 +1,7 @@
 import path from 'node:path';
+import { inspectHelperExpansion } from '../core/helper-expansion.js';
+import { technologyHelperInventory } from './helper-expansion.js';
+import { clearSemanticDependencies } from '../core/semantic-dependencies.js';
 import { canonicalJson, compareCodeUnits, hashCanonical, sha256Bytes } from '../core/canonical.js';
 import { boundedSourceHashEvidence, } from '../core/artifacts.js';
 import { RenderBudget } from '../core/render-budget.js';
@@ -9,7 +12,7 @@ import { PACKAGE_VERSION } from '../version.js';
 import { GuiAssetCatalog } from '../gui/assets.js';
 import { buildGuiSourceGraph } from '../gui/source-graph.js';
 import { compareTechnologyGraphs } from './compare.js';
-import { buildTechnologyGraph, technologyAssetPatterns } from './graph.js';
+import { buildTechnologyGraph, buildTechnologyGraphAsync, technologyAssetPatterns, } from './graph.js';
 import { TECHNOLOGY_GRAPH_SCHEMA_VERSION } from './model.js';
 import { analyzeTechnologyImpact, discoverTechnologyFolders, explainTechnology, inspectTechnologyUnlocks, lintTechnologyGraph, technologyBonusCoverage, technologyScanReport, traceTechnology, } from './queries.js';
 import { renderTechnologyGraph, technologyRenderIconSprites, } from './render.js';
@@ -48,6 +51,7 @@ class BoundedTechnologyFragmentCache {
         }
     }
     clear() {
+        clearSemanticDependencies(this);
         this.#values.clear();
         this.#bytes = 0;
     }
@@ -445,16 +449,17 @@ export class TechnologyTreeViewer {
         const workspace = this.engine.resolver.get(workspaceId, options.principal);
         const generation = this.engine.generation(workspaceId);
         const cached = this.#state.current.get(workspaceId);
-        if (options.refresh !== true && cached?.generation === generation)
-            return cached.graph;
         const snapshot = await scanTechnologySources(this.engine, workspaceId, workspace, options.principal, options.signal);
         const analysisMode = 'full';
-        const preliminary = buildTechnologyGraph(snapshot, {
-            workspaceIdentity: workspace.workspaceIdentity,
-            cache: this.#state.fragments,
-            analysisMode,
-            ...(options.signal === undefined ? {} : { signal: options.signal }),
-        });
+        const unchangedSource = cached?.generation === generation && cached.snapshot.revision === snapshot.revision;
+        const preliminary = unchangedSource
+            ? cached.graph
+            : await buildTechnologyGraphAsync(snapshot, {
+                workspaceIdentity: workspace.workspaceIdentity,
+                cache: this.#state.fragments,
+                analysisMode,
+                ...(options.signal === undefined ? {} : { signal: options.signal }),
+            });
         const patterns = technologyAssetPatterns(preliminary);
         const assetFiles = patterns.length === 0
             ? []
@@ -462,7 +467,15 @@ export class TechnologyTreeViewer {
                 patterns,
                 ...(options.signal === undefined ? {} : { signal: options.signal }),
             });
-        const graph = buildTechnologyGraph(snapshot, {
+        const assetIdentity = (files) => hashCanonical(files.map(({ absolutePath, displayPath, loadOrder, sha256 }) => ({
+            absolutePath,
+            displayPath,
+            loadOrder,
+            sha256,
+        })));
+        if (unchangedSource && assetIdentity(assetFiles) === assetIdentity(cached.assetFiles))
+            return cached.graph;
+        const graph = await buildTechnologyGraphAsync(snapshot, {
             workspaceIdentity: workspace.workspaceIdentity,
             cache: this.#state.fragments,
             assetFiles,
@@ -474,6 +487,24 @@ export class TechnologyTreeViewer {
         return graph;
     }
     async analyze(input) {
+        if (input.mode === 'helper_expansion') {
+            const workspace = this.engine.resolver.get(input.workspaceId, input.principal);
+            const snapshot = await scanTechnologySources(this.engine, input.workspaceId, workspace, input.principal, input.signal);
+            const graph = await buildTechnologyGraphAsync(snapshot, {
+                workspaceIdentity: workspace.workspaceIdentity,
+                cache: this.#state.fragments,
+                analysisMode: 'focused',
+                ...(input.signal === undefined ? {} : { signal: input.signal }),
+            });
+            const expansion = await inspectHelperExpansion(this.engine, input.workspaceId, technologyHelperInventory(graph, snapshot.complete && graph.unresolved.every(({ kind }) => kind !== 'partial_source')), input.helperExpansion, input.principal, input.signal);
+            return {
+                graph,
+                report: expansion.report,
+                reportJson: expansion.reportJson,
+                artifacts: expansion.artifacts,
+                helperExpansion: expansion.summary,
+            };
+        }
         const graph = await this.scan(input.workspaceId, {
             refresh: input.refresh ?? input.mode === 'scan',
             ...(input.principal === undefined ? {} : { principal: input.principal }),
@@ -542,11 +573,37 @@ export class TechnologyTreeViewer {
             complete: graph.complete,
             analysisBoundary: graph.analysisBoundary,
             mode: input.mode,
+            resources: [
+                {
+                    name: `${safeSlug(`technology-${input.mode}`)}-${graph.revision.slice(0, 12)}.json`,
+                    mimeType: 'application/json',
+                },
+                ...(input.mode === 'scan'
+                    ? [
+                        {
+                            name: `technology-graph-${graph.revision}.json`,
+                            mimeType: 'application/json',
+                        },
+                    ]
+                    : []),
+            ],
             report,
         })}\n`;
         const workspace = this.engine.resolver.get(input.workspaceId, input.principal);
+        const graphHashValue = graphHash(graph);
         const artifact = await this.engine.artifacts.putChunked(workspace, `${safeSlug(`technology-${input.mode}`)}-${graph.revision.slice(0, 12)}.json`, 'application/json', reportJson, technologyProvenance(graph, `technology-${input.mode}`, { mode: input.mode }), `Authoritative Technology Tree Viewer ${input.mode.replaceAll('_', ' ')} report`, input.signal);
-        return { graph, report, reportJson, artifacts: [artifact] };
+        const graphArtifact = input.mode === 'scan'
+            ? await this.engine.artifacts.putChunked(workspace, `technology-graph-${graph.revision}.json`, 'application/json', `${canonicalJson({ schemaVersion: 'technology-graph-snapshot.v1', graph })}\n`, technologyProvenance(graph, 'technology-graph-snapshot', {
+                revision: graph.revision,
+                graphHash: graphHashValue,
+            }), 'Revision-addressed Technology Tree Viewer graph snapshot', input.signal)
+            : undefined;
+        return {
+            graph,
+            report,
+            reportJson,
+            artifacts: [artifact, ...(graphArtifact === undefined ? [] : [graphArtifact])],
+        };
     }
     async renderAndStore(input) {
         const graph = await this.scan(input.workspaceId, {
@@ -747,10 +804,27 @@ export class TechnologyTreeViewer {
             return graph;
         }
         if (reference?.revision !== undefined) {
-            const graph = this.#state.history.get(workspaceId)?.get(reference.revision);
-            if (graph === undefined)
-                throw new ServiceError('TECH_REVISION_NOT_CACHED', 'Requested technology revision is not cached');
-            return graph;
+            const cached = this.#state.history.get(workspaceId)?.get(reference.revision);
+            if (cached !== undefined)
+                return cached;
+            const workspace = this.engine.resolver.get(workspaceId, principal);
+            const names = new Set([
+                `technology-graph-${reference.revision}.json`,
+                `technology-scan-${reference.revision.slice(0, 12)}.json`,
+            ]);
+            const candidates = (await this.engine.artifacts.list(workspace, signal)).filter(({ name }) => names.has(name));
+            for (const artifact of candidates) {
+                const selected = parseGraphArtifact(await readLogicalArtifact(this.engine, workspaceId, artifact.uri, principal, signal));
+                if (selected.revision === reference.revision &&
+                    selected.workspaceId === workspaceId &&
+                    selected.workspaceIdentity === current.workspaceIdentity) {
+                    rememberGraph(this.#state, selected);
+                    return selected;
+                }
+            }
+            if (candidates.length === 0)
+                throw new ServiceError('TECH_REVISION_NOT_CACHED', 'Requested technology revision is not cached or retained as a graph artifact');
+            throw new ServiceError('TECH_GRAPH_WORKSPACE_MISMATCH', 'Retained technology graph evidence does not match the requested revision and workspace topology');
         }
         return current;
     }

package/dist/hoi4_agent_tools/technology/source-analysis.js

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { semanticSourceIdentity } from '../core/semantic-dependencies.js';
 import { compareCodeUnits, deterministicId } from '../core/canonical.js';
 import { assignments, childBlocks, firstScalar, nodeLocation, parseClausewitz, sourcePartialLimitDiagnostics, } from '../core/source/index.js';
 const technologyStructuralFields = new Set([
@@ -1031,7 +1032,7 @@ export function analyzeTechnologySource(file, context) {
     return fragment;
 }
 export function technologySourceFragmentCacheKey(file, catalogFingerprint) {
-    return `${file.sha256}:${catalogFingerprint}`;
+    return `${semanticSourceIdentity(file)}:${catalogFingerprint}`;
 }
 export function technologySourceFiles(files) {
     return files

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.0.9';
+export const PACKAGE_VERSION = '3.1.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,8 @@
 - [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.
 - [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.
 - [AI and MTTH analysis](probability.md): evaluate weighted logic, timing, uncertainty, sequences, and patches.
 - [Focus trees](focus.md): inspect, create, render, and clean national or continuous focus content.
 - [Scripted GUIs](gui.md): inspect linked UI source, render states, and create or repair GUIs.

package/docs/development.md

@@ -25,6 +25,8 @@ The technology acceptance fixture contains 1,040 project-owned technologies acro
 
 `npx vitest run tests/integration/mcp-concurrent-workloads.test.ts` tests simultaneous production calls across all six domains over six HTTP sessions and four independent stdio processes, including artifact retrieval and queued cancellation. Execution limits and connection behavior are described in [HTTP](http.md) and the [concurrency decision](https://github.com/klimPaskov/hoi4-agent-tools/blob/main/docs/adr/0026-concurrent-request-execution.md).
 
+Persistent-job qualification covers authenticated record publication, request-key conflicts, read-result checkpoints, transaction-journal reconciliation, stopped-owner takeover, native task negotiation, ordinary-call parity, reconnect isolation, rewrite cancellation before source application, and fixed-entry worker execution. The public lifecycle contract is documented in [Persistent jobs and MCP tasks](jobs.md).
+
 The probability fixture contains more than 150 weighted blocks, 250 scenarios, and a declared stateful pool. Run `npm run benchmark` after analyzer changes. On the July 22, 2026 reference run, cold indexing took 28 ms, a cached block evaluation 29 ms, the 250-row matrix 85 ms, one million draws 9 ms, 3/12/25-candidate sequence cases 20/2,079/356 ms, and retrieval of a 1.84 MB result 3 ms. Review budgets are 250 ms, 150 ms, 750 ms, 100 ms, 200/10,000/3,000 ms, and 100 ms respectively; accuracy, method metadata, and omitted probability must not be weakened to meet them.
 
 Local opt-in tests can also read an installed game and an external mod without copying their sources:

package/docs/events.md

@@ -6,7 +6,7 @@ Use the three event tools directly from the target mod.
 
 ## Inspect
 
-`hoi4.event_inspect` provides seven focused modes:
+`hoi4.event_inspect` provides eight focused modes:
 
 - `scan`: inventory event definitions, namespaces, call sites, and unresolved references.
 - `roots`: find likely entry points and explain why they are roots.
@@ -15,8 +15,13 @@ Use the three event tools directly from the target mod.
 - `state_flow`: report flags, variables, targets, scopes, and other tracked state read or changed along a route.
 - `lint`: find missing targets, unreachable events, suspicious cycles, conflicting definitions, invalid timing, and unresolved dynamic calls.
 - `impact`: identify callers, descendants, state dependencies, and files affected by a proposed event change.
+- `helper_expansion`: stream bounded source-linked helper-call paths, dispatches, and state accesses with revision-bound continuation.
 
-Use narrow identifiers, direction, and depth limits when the task concerns one chain. Broad scans build the structural event graph without expanding every scripted helper into duplicate paths. Game-backed or other large workspaces automatically use a focused source profile containing event definitions and on-actions, then defer workspace-wide helper projections and lifecycle passes. The result is marked partial and records that boundary in the linked evidence instead of waiting until the MCP transport times out. Focused trace and path calls collapse only the selected bounded route.
+Use narrow identifiers, direction, and depth limits when the task concerns one chain.
+Broad scans build the structural event graph without expanding every scripted helper into duplicate paths.
+Focused trace, path, and selector-based inventory requests may defer workspace-wide helper projections and lifecycle passes; their linked evidence records the partial boundary.
+Focused trace and path calls collapse only the selected bounded route.
+For a large helper closure, use [bounded helper expansion](helper-expansion.md) to receive resumable pages without first materializing every projection.
 
 The compact response summarizes the result. Small scan resources contain the complete graph; large scan resources contain exact totals, grouped inventories, representative diagnostics, and the revision needed for focused follow-up queries. Large focused scans keep direct event and on-action evidence, call sites, state accesses, and source locations while leaving helper expansion and workspace-wide lifecycle analysis explicit as deferred boundaries. This keeps an agent's prompt and artifact storage bounded without allowing a broad scan to exhaust the MCP process.
 

package/docs/helper-expansion.md

@@ -0,0 +1,78 @@
+# Bounded helper expansion
+
+`hoi4.event_inspect` and `hoi4.tech_inspect` accept `mode: "helper_expansion"`.
+This is a read-only stream of source-linked helper paths, not a source rewrite or runtime simulation.
+It avoids materializing the whole helper closure before returning its first page.
+
+Start either tool with:
+
+```json
+{
+  "mode": "helper_expansion",
+  "helperExpansion": { "maxRecords": 250, "maxWork": 5000, "maxDepth": 64 }
+}
+```
+
+If `data.helperExpansion.finished` is false, pass its opaque `continuationUri` to the same tool:
+
+```json
+{
+  "mode": "helper_expansion",
+  "helperExpansion": { "continuationUri": "<data.helperExpansion.continuationUri>" }
+}
+```
+
+The server restores root selection and depth from the continuation.
+Page size and work limit may change between calls; root selection and depth may not.
+A continuation may be used by a fresh server process with the same configured workspace, authorized principal, tool version, and exact source revision.
+Every resume re-enumerates and verifies source bytes, even if `refresh` is omitted.
+Changed source, domain, root topology, principal, or query is rejected explicitly rather than merged into earlier evidence.
+To analyze edited source or use a different depth, start a new request without the continuation.
+
+## Bounds and evidence
+
+`helperExpansion` has these optional fields:
+
+| Field             | Contract                                                                                                                                                                 |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `rootIds`         | Up to 2,000 exact structural helper-call root IDs; omitted means all recognized non-helper callers. Obtain IDs from a page's `rootId` or the linked ordinary scan graph. |
+| `maxDepth`        | 1–256 helper calls, default 64.                                                                                                                                          |
+| `maxRecords`      | 1–5,000 records per page, default 250.                                                                                                                                   |
+| `maxWork`         | 1–100,000 traversal transitions per page, default 5,000.                                                                                                                 |
+| `continuationUri` | Opaque sibling resource returned in the prior tool result. Do not edit or construct it.                                                                                  |
+
+Other inspection filters such as top-level `maxDepth`, `selector`, and `technologyId` are rejected in this mode rather than silently ignored.
+The shared dependency inventory is limited to one million edges; source, parser, and artifact byte limits also remain enforced.
+`maxWork` bounds dependency traversal, not the mandatory source scan or parsing.
+An empty page can still advance work; continue when `finished` is false.
+
+The linked JSON contains ordered `records` with `visit`, `terminal`, `cycle`, or `depth` kinds.
+Each record links its root and exact edge-ID path to a page-local `edges` evidence table.
+Event leaves include dispatches and helper-owned state accesses with their conditions, locations, and scope evidence.
+Technology leaves include helper-owned grants, bonuses, and other technology references with source-linked call paths.
+Different structural calls to the same helper remain distinct paths, including parallel calls under different conditions.
+The technology call model links conditions through source locations; it does not evaluate or reconstruct runtime trigger outcomes.
+Ordinary inspect modes remain the route for direct non-helper references and aggregate graph diagnostics.
+
+`finished` means every selected root has been visited under the stated cycle and depth policy.
+`complete` additionally requires complete source inventory and zero depth stops.
+Cycles are reported and stopped at the repeated ancestor; completion describes finite simple-path coverage, not recursive execution.
+Dynamic and missing source references remain unresolved findings, with exact counts and at most 100 samples in each page report.
+Completion never establishes that those findings are resolved or that a runtime outcome is known.
+The cumulative record, work, root, cycle, and depth counters describe the entire resumed traversal, while `records` and `work` in the tool summary describe the current page.
+
+The page report and its continuation are published together through the shared atomic artifact store.
+The continuation is also linked as a sibling artifact; its resource URI is in the compact tool result, not reconstructed from a filename.
+Cursor storage retains the active ancestor stack rather than completed paths.
+Artifacts follow configured retention and admission limits; an evicted or unavailable cursor fails explicitly and requires a fresh analysis.
+This is not permanent storage of every historical page.
+
+## Compatibility and boundaries
+
+This opt-in mode and optional result summary are additive in 3.1.0.
+Existing inspection modes retain their own ordering, representative-path policy, and materialization limits.
+A depth- or projection-truncated materialized graph reports incomplete coverage.
+The paged edge-path stream must not be mistaken for the deduplicated projections in those graphs.
+Ordinary calls and persisted jobs return the same page contract.
+Within-page work is bounded; the existing durable result checkpoint handles interruption after a page result has been staged.
+Broader materialized-graph memory refinement remains separate from this bounded page contract.

package/docs/http.md

@@ -10,6 +10,8 @@ JSON request bodies default to and are capped at 64 MiB, with a shared 128 MiB b
 
 `maxConcurrentTools` controls expensive operations per server engine (default 2), and `maxSharedTools` controls operations across local processes sharing the same `serverStateRoot` (default 4). Calls waiting for capacity remain cancellable and emit progress when requested. Increase execution capacity only when the host has enough memory for the corresponding scans and renders. HTTP admission, connection, session, and rate limits remain separately configurable.
 
+Optional MCP tasks are backed by authenticated state beneath `serverStateRoot`, not by one HTTP connection. A task therefore survives disconnect and reconnect for the same principal, while another principal cannot list, inspect, cancel, or retrieve it. Native rewrites additionally require `hoi4:write` and a stable `requestKey`. See [Persistent jobs and MCP tasks](jobs.md) for retry, cancellation, and retention semantics.
+
 Resumable event history defaults to 2 MiB per session within the 16 MiB global store, enough to retain one framed 1 MiB artifact-resource chunk.
 
 ## Loopback

package/docs/jobs.md

@@ -0,0 +1,85 @@
+# Persistent jobs and MCP tasks
+
+Long-running domain operations support optional MCP tasks while preserving the ordinary tool-call contract.
+Clients that negotiate task support can request a task, disconnect, reconnect with the same authorized identity, inspect or cancel it, and retrieve the original tool result after completion.
+Clients that do not request a task continue to receive the same synchronous tool result as before.
+
+Version 3.1.0 routes 2025-era clients through the existing stateful adapter and 2026-07-28 clients through the [modern operation/task adapter](adr/0031-modern-mcp-task-adapter.md) on both stdio and HTTP.
+Modern requests independently negotiate the Tasks extension, use authenticated flat handles, and receive terminal results in `tasks/get`.
+
+Clients can request ordinary-call progress with a progress token.
+Both protocol adapters share strictly increasing updates and bounded-frequency heartbeats, with cleanup when the request completes, fails, or is cancelled.
+The modern route uses request-related notifications and automatically streams an HTTP response when a progress update is emitted, while silent calls retain JSON responses.
+A modern native task handoff ends that request's heartbeat without declaring the underlying worker complete; clients retrieve ongoing status messages through `tasks/get`.
+
+## Supported tools
+
+Optional tasks are available for every read-only event, technology, probability, map, GUI, and focus operation, and for the three rewrite tools:
+
+- `hoi4.event_inspect`, `hoi4.event_render`, and `hoi4.event_compare`
+- `hoi4.tech_inspect`, `hoi4.tech_render`, and `hoi4.tech_compare`
+- `hoi4.probability_inspect`, `hoi4.probability_evaluate`, `hoi4.probability_sweep`, `hoi4.probability_simulate`, `hoi4.probability_sequence`, `hoi4.probability_compare`, and `hoi4.probability_render`
+- `hoi4.map_inspect`, `hoi4.map_render`, and `hoi4.map_rewrite`
+- `hoi4.gui_inspect`, `hoi4.gui_render`, and `hoi4.gui_rewrite`
+- `hoi4.focus_inspect`, `hoi4.focus_render`, `hoi4.focus_raster`, and `hoi4.focus_rewrite`
+
+Task results are exact tool results, including linked artifacts, partial-analysis markers, validation evidence, and tool-level errors.
+A completed tool-level error is therefore a completed task whose result has `isError: true`; an execution or storage failure is a failed task.
+
+## Rewrite request keys
+
+A native background rewrite must include a caller-generated `requestKey` between 1 and 256 characters.
+Reuse the same key only for retries of the same rewrite request.
+The key's receipt namespace is scoped to the authenticated principal, workspace identity, and workspace roots, and the receipt binds the original tool, inputs, and tool version.
+Do not reuse a key for a different tool in the same namespace.
+Repeating an identical request with the same key returns the same task and durable result even if task polling or retention hints changed; reusing the key with different rewrite inputs fails explicitly.
+Ordinary synchronous rewrite calls do not require `requestKey`.
+An exact keyed retry after task visibility expires renews the task's polling window and retrieves the saved outcome without applying the rewrite again.
+This also preserves failed and cancelled outcomes; a retry key cannot restart a terminal operation.
+Both native and ordinary calls use that same receipt, while a conflicting retry or status lookup cannot extend its visibility.
+
+The server binds an applied rewrite to its authenticated transaction journal before source replacement starts.
+If execution stops after a commit, recovery reads that journal and reconstructs the domain result without planning or applying the rewrite again.
+Blocked and unchanged plans do not bind a transaction because they never mutate source.
+
+## Cancellation and recovery
+
+Cancellation is durable and cooperative.
+A queued cancellation becomes terminal without starting source work.
+A running cancellation is observed by the isolated worker; if a rewrite has already crossed the commit boundary, reconciliation reports the actual committed or restored outcome instead of inventing a cancellation or replaying the request.
+Cancelling an ordinary synchronous call prevents admission when possible and otherwise requests cooperative cancellation of its durable job.
+Closing the originating connection does not cancel an accepted native task.
+
+Read-only jobs stage a source-revision-bound result checkpoint before terminal publication.
+If a worker or server stops after that checkpoint, a later authorized process publishes the retained result without rerunning the operation.
+Event and technology helper expansion also saves an authenticated intermediate frontier with its exact source revision and traversal contract.
+A replacement validates the saved paths, adjacency cursor, graph identity, and checkpoint bytes before continuing.
+Source changes before intermediate-frontier recovery cause a fresh analysis of the current revision; old and new graph evidence are never combined.
+An active host allows at most two replacement attempts after proven worker death, and never retries the same unchanged frontier twice.
+Checkpoint recovery never overrides cancellation or live/unverifiable ownership, and never replays a rewrite.
+Event and technology scan artifacts retain revision-addressed graphs for later comparisons, and bounded responses state their requested depth, node, edge, render, helper-expansion, or candidate coverage.
+Their opt-in `helper_expansion` mode also returns [bounded continuation pages](helper-expansion.md) through both ordinary calls and persistent jobs.
+Unlike automatic recovery inside a single job, an explicit page resume after a source edit is rejected so a caller cannot combine old and new pages.
+
+Workers use fixed registered operations in separate Node.js processes.
+Job records contain validated JSON inputs and authenticated state; they cannot select modules, executables, or arbitrary commands.
+Workspace and principal authorization is rechecked for every submission, lookup, list, result retrieval, and cancellation.
+
+## Compatibility tools and retention
+
+`hoi4.job_inspect` returns bounded status for an active, cancelled, or failed job and returns the original tool result for a completed job.
+`hoi4.job_cancel` records an authorized cancellation request.
+Both are control-plane operations and remain responsive while domain execution slots are occupied.
+Both protocol adapters use the same control service, and these calls remain foreground operations even when a modern caller advertises the Tasks extension.
+Job records are principal-private, including when another principal has access to the same workspace; this differs from artifacts shared within authorized workspace grants.
+
+Native task identifiers include the workspace and persistent job identifier.
+They are opaque client values; transaction identifiers and plan hashes are never public workflow inputs.
+New persistent job IDs are derived from private server state, and earlier authenticated retry receipts remain usable without repeating their original operation.
+The modern adapter adds an authenticated handle suffix, including when it references an earlier receipt, so clients must retain the complete task ID rather than reconstructing it from job metadata or reusing a handle from another protocol generation.
+Read-only terminal jobs follow the negotiated task retention period, clamped between one minute and seven days with a 24-hour default.
+Mutation receipts remain durable after task visibility expires so a retry cannot duplicate an uncertain write.
+Renewed task responses report their total lifetime from the original creation time, including elapsed age, while the newly granted visibility window remains bounded.
+
+Persistent tasks require an operator-owned `serverStateRoot`.
+HTTP principals can see only jobs within their existing workspace grants, and rewrite submission or cancellation also requires `hoi4:write`.

package/docs/technology.md

@@ -6,7 +6,7 @@ Use the three technology tools directly from the target mod.
 
 ## Inspect
 
-`hoi4.tech_inspect` provides eight focused modes:
+`hoi4.tech_inspect` provides nine focused modes:
 
 - `scan`: build the technology graph and report its inventory, diagnostics, analysis limits, and revision. Small graphs include the complete graph in the report; large graphs return exact counts, grouped findings, samples, and the revision for focused follow-up queries.
 - `folders`: list folder roots and source placements, or inspect one `folderId`.
@@ -16,6 +16,7 @@ Use the three technology tools directly from the target mod.
 - `bonus_coverage`: show which technologies or categories are covered by discovered research bonuses.
 - `lint`: filter source-linked findings by classification, diagnostic code, folder, or technology.
 - `impact`: find the definitions, placements, edges, grants, bonuses, unlocks, localisation, sprites, and files affected by a proposed removal or rename.
+- `helper_expansion`: stream source-linked scripted-effect call paths and helper-owned technology references with bounded pages and revision-bound continuation.
 
 Example trace:
 
@@ -45,7 +46,10 @@ Impact mode takes a subject with `kind` set to `technology`, `category`, `folder
 
 Findings are separated into confirmed errors, probable defects, design warnings, and unresolved analysis. Roots, grant-only technologies, early dates, zero AI weights, repeated effects, and routing nodes are evaluated in context instead of being treated as automatic defects. The viewer keeps its authoritative graph in memory while the linked scan artifact remains a bounded summary; use its revision with the focused inspect modes or a render resource to inspect the relevant records.
 
-Game-backed and otherwise large workspaces automatically use focused analysis mode. It keeps direct grants, bonuses, unlocks, definitions, and the source-linked scripted-effect call index while deferring the full helper projection that can otherwise make a vanilla-plus-mod scan take minutes or exhaust the server process. The result is marked partial and names this boundary in `analysisBoundary`; no direct source evidence is discarded.
+Ordinary technology inspection uses the materialized graph and its explicit helper-depth and projection limits.
+A truncated helper expansion reports incomplete coverage.
+For a large helper closure, [bounded helper expansion](helper-expansion.md) uses the structural call inventory and streams source-linked paths without first materializing the full projection.
+It preserves separate conditional call sites and identifies source, cycle, and depth boundaries without simulating trigger outcomes.
 
 ## Render
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hoi4-agent-tools",
   "mcpName": "io.github.klimPaskov/hoi4-agent-tools",
-  "version": "3.0.9",
+  "version": "3.1.0",
   "description": "Analyze HOI4 events, tech trees, AI weights, and MTTH; build focus trees, GUIs, and maps.",
   "type": "module",
   "license": "Apache-2.0",
@@ -47,6 +47,8 @@
     "docs/map.md",
     "docs/http.md",
     "docs/development.md",
+    "docs/jobs.md",
+    "docs/helper-expansion.md",
     "docs/images/readme/",
     "examples/clients/",
     "examples/probability/",
@@ -99,23 +101,27 @@
   },
   "dependencies": {
     "@fontsource-variable/roboto": "5.3.0",
+    "@modelcontextprotocol/core": "2.0.0",
+    "@modelcontextprotocol/node": "2.0.0",
     "@modelcontextprotocol/sdk": "1.30.0",
+    "@modelcontextprotocol/server": "2.0.0",
     "express": "5.2.1",
     "fast-glob": "3.3.3",
     "fontkit": "2.0.4",
     "iconv-lite": "0.7.3",
     "jose": "6.2.8",
-    "sharp": "0.35.3",
+    "sharp": "0.35.4",
     "zod": "4.4.3"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
+    "@modelcontextprotocol/client": "2.0.0",
     "@modelcontextprotocol/inspector": "2.1.0",
     "@types/express": "5.0.6",
     "@types/fontkit": "2.0.9",
     "@types/node": "22.20.1",
     "@types/pixelmatch": "5.2.6",
-    "@vitest/coverage-v8": "4.1.10",
+    "@vitest/coverage-v8": "4.1.11",
     "ajv": "8.20.0",
     "ajv-formats": "3.0.1",
     "eslint": "10.8.1",
@@ -125,14 +131,14 @@
     "tsx": "4.23.11",
     "typescript": "6.0.3",
     "typescript-eslint": "8.66.0",
-    "vitest": "4.1.10"
+    "vitest": "4.1.11"
   },
   "overrides": {
     "@hono/node-server": "2.1.0",
     "brace-expansion": "5.0.9",
     "fast-uri": "3.1.7",
     "qs": "6.16.0",
-    "hono": "4.13.1",
+    "hono": "4.13.8",
     "nanoid": "3.3.18",
     "ip-address": "10.4.0",
     "postcss": "8.5.26",

package/schemas/configuration.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.0.9/schemas/configuration.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.1.0/schemas/configuration.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {