hoi4-agent-tools 3.0.8 → 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (135) hide show
  1. package/CHANGELOG.md +35 -1
  2. package/README.md +4 -0
  3. package/dist/bin/stdio.js +23 -12
  4. package/dist/hoi4_agent_tools/core/analysis-checkpoints.js +82 -0
  5. package/dist/hoi4_agent_tools/core/artifact-resource.js +173 -0
  6. package/dist/hoi4_agent_tools/core/artifacts.js +84 -2
  7. package/dist/hoi4_agent_tools/core/condition-evaluator.js +399 -0
  8. package/dist/hoi4_agent_tools/core/condition-model.js +1 -0
  9. package/dist/hoi4_agent_tools/core/condition-schema.js +42 -0
  10. package/dist/hoi4_agent_tools/core/dependency-pages.js +216 -0
  11. package/dist/hoi4_agent_tools/core/dependency-walk.js +266 -0
  12. package/dist/hoi4_agent_tools/core/domain-validation.js +188 -0
  13. package/dist/hoi4_agent_tools/core/engine.js +48 -5
  14. package/dist/hoi4_agent_tools/core/helper-expansion.js +186 -0
  15. package/dist/hoi4_agent_tools/core/index-segments.js +137 -0
  16. package/dist/hoi4_agent_tools/core/index.js +47 -4
  17. package/dist/hoi4_agent_tools/core/job-controls.js +109 -0
  18. package/dist/hoi4_agent_tools/core/job-executor.js +190 -0
  19. package/dist/hoi4_agent_tools/core/job-service.js +112 -0
  20. package/dist/hoi4_agent_tools/core/job-store.js +641 -0
  21. package/dist/hoi4_agent_tools/core/job-transactions.js +126 -0
  22. package/dist/hoi4_agent_tools/core/job-worker-host.js +200 -0
  23. package/dist/hoi4_agent_tools/core/job-worker.js +62 -0
  24. package/dist/hoi4_agent_tools/core/operation-context.js +31 -0
  25. package/dist/hoi4_agent_tools/core/operation-result.js +412 -0
  26. package/dist/hoi4_agent_tools/core/operation-tasks.js +382 -0
  27. package/dist/hoi4_agent_tools/core/persistent-analysis-cache.js +383 -0
  28. package/dist/hoi4_agent_tools/core/result.js +1 -0
  29. package/dist/hoi4_agent_tools/core/scanner.js +15 -75
  30. package/dist/hoi4_agent_tools/core/scenario-state.js +97 -0
  31. package/dist/hoi4_agent_tools/core/semantic-dependencies.js +233 -0
  32. package/dist/hoi4_agent_tools/core/shared-request-capacity.js +74 -25
  33. package/dist/hoi4_agent_tools/core/source/cache.js +107 -0
  34. package/dist/hoi4_agent_tools/core/source/parser.js +11 -1
  35. package/dist/hoi4_agent_tools/core/transaction-execution.js +134 -0
  36. package/dist/hoi4_agent_tools/core/transactions.js +80 -27
  37. package/dist/hoi4_agent_tools/event/graph.js +214 -290
  38. package/dist/hoi4_agent_tools/event/helper-expansion.js +33 -0
  39. package/dist/hoi4_agent_tools/event/job-operations.js +51 -0
  40. package/dist/hoi4_agent_tools/event/operations.js +179 -0
  41. package/dist/hoi4_agent_tools/event/service.js +67 -15
  42. package/dist/hoi4_agent_tools/event/source-analysis.js +5 -4
  43. package/dist/hoi4_agent_tools/focus/job-operations.js +77 -0
  44. package/dist/hoi4_agent_tools/focus/tool-operations.js +669 -0
  45. package/dist/hoi4_agent_tools/focus/tool-support.js +123 -0
  46. package/dist/hoi4_agent_tools/gui/job-operations.js +81 -0
  47. package/dist/hoi4_agent_tools/gui/scenario-conditions.js +119 -0
  48. package/dist/hoi4_agent_tools/gui/scenario-generator.js +59 -73
  49. package/dist/hoi4_agent_tools/gui/scenario.js +3 -0
  50. package/dist/hoi4_agent_tools/gui/studio.js +5 -2
  51. package/dist/hoi4_agent_tools/gui/tool-operations.js +270 -0
  52. package/dist/hoi4_agent_tools/map/job-operations.js +76 -0
  53. package/dist/hoi4_agent_tools/map/tool-operations.js +493 -0
  54. package/dist/hoi4_agent_tools/mcp/prompts/probability.js +25 -0
  55. package/dist/hoi4_agent_tools/mcp/prompts/register-modern.js +29 -0
  56. package/dist/hoi4_agent_tools/mcp/resources/register-modern.js +34 -0
  57. package/dist/hoi4_agent_tools/mcp/resources/register.js +4 -150
  58. package/dist/hoi4_agent_tools/mcp/server/base-tools.js +3 -219
  59. package/dist/hoi4_agent_tools/mcp/server/create-modern-operations.js +188 -0
  60. package/dist/hoi4_agent_tools/mcp/server/create.js +16 -6
  61. package/dist/hoi4_agent_tools/mcp/server/instructions.js +2 -0
  62. package/dist/hoi4_agent_tools/mcp/server/job-task-store.js +67 -0
  63. package/dist/hoi4_agent_tools/mcp/server/legacy-task-tools.js +20 -0
  64. package/dist/hoi4_agent_tools/mcp/server/modern-tasks.js +168 -0
  65. package/dist/hoi4_agent_tools/mcp/server/progress.js +17 -15
  66. package/dist/hoi4_agent_tools/mcp/server/request-lifecycle.js +43 -0
  67. package/dist/hoi4_agent_tools/mcp/server/result.js +2 -412
  68. package/dist/hoi4_agent_tools/mcp/server/task-request-context.js +9 -0
  69. package/dist/hoi4_agent_tools/mcp/server/task-tool-catalog.js +14 -0
  70. package/dist/hoi4_agent_tools/mcp/server/task-tool-definition.js +1 -0
  71. package/dist/hoi4_agent_tools/mcp/server/transaction-execution.js +1 -123
  72. package/dist/hoi4_agent_tools/mcp/tools/chaosx.js +38 -21
  73. package/dist/hoi4_agent_tools/mcp/tools/event.js +24 -315
  74. package/dist/hoi4_agent_tools/mcp/tools/focus.js +34 -1039
  75. package/dist/hoi4_agent_tools/mcp/tools/gui.js +19 -504
  76. package/dist/hoi4_agent_tools/mcp/tools/job.js +46 -0
  77. package/dist/hoi4_agent_tools/mcp/tools/map.js +21 -600
  78. package/dist/hoi4_agent_tools/mcp/tools/probability.js +39 -463
  79. package/dist/hoi4_agent_tools/mcp/tools/technology.js +40 -304
  80. package/dist/hoi4_agent_tools/mcp/transports/http.js +58 -1
  81. package/dist/hoi4_agent_tools/mcp/transports/modern-task-routing.js +109 -0
  82. package/dist/hoi4_agent_tools/mcp/transports/negotiated-stdio.js +121 -0
  83. package/dist/hoi4_agent_tools/probability/job-operations.js +58 -0
  84. package/dist/hoi4_agent_tools/probability/operations.js +183 -0
  85. package/dist/hoi4_agent_tools/probability/scenario-state.js +2 -95
  86. package/dist/hoi4_agent_tools/probability/service.js +24 -3
  87. package/dist/hoi4_agent_tools/probability/trigger-evaluator.js +1 -287
  88. package/dist/hoi4_agent_tools/schemas/common.js +2 -0
  89. package/dist/hoi4_agent_tools/schemas/event.js +72 -1
  90. package/dist/hoi4_agent_tools/schemas/focus-requests.js +189 -0
  91. package/dist/hoi4_agent_tools/schemas/gui-requests.js +193 -0
  92. package/dist/hoi4_agent_tools/schemas/helper-expansion.js +58 -0
  93. package/dist/hoi4_agent_tools/schemas/map-requests.js +85 -0
  94. package/dist/hoi4_agent_tools/schemas/probability-requests.js +168 -0
  95. package/dist/hoi4_agent_tools/schemas/technology.js +90 -1
  96. package/dist/hoi4_agent_tools/schemas/transaction.js +1 -0
  97. package/dist/hoi4_agent_tools/technology/graph.js +83 -78
  98. package/dist/hoi4_agent_tools/technology/helper-expansion.js +33 -0
  99. package/dist/hoi4_agent_tools/technology/job-operations.js +60 -0
  100. package/dist/hoi4_agent_tools/technology/operations.js +125 -0
  101. package/dist/hoi4_agent_tools/technology/service.js +89 -15
  102. package/dist/hoi4_agent_tools/technology/source-analysis.js +2 -1
  103. package/dist/hoi4_agent_tools/version.js +1 -1
  104. package/docs/README.md +2 -0
  105. package/docs/development.md +2 -0
  106. package/docs/events.md +7 -2
  107. package/docs/gui.md +3 -1
  108. package/docs/helper-expansion.md +78 -0
  109. package/docs/http.md +2 -0
  110. package/docs/jobs.md +85 -0
  111. package/docs/technology.md +6 -2
  112. package/package.json +11 -5
  113. package/schemas/configuration.schema.json +1 -1
  114. package/schemas/continuous-focus-palette.schema.json +1 -1
  115. package/schemas/custom-weighted-pool.schema.json +1 -1
  116. package/schemas/event-feature-manifest.schema.json +1 -1
  117. package/schemas/focus-plan.schema.json +1 -1
  118. package/schemas/focus-planning-sidecar.schema.json +1 -1
  119. package/schemas/gui-animation-source.schema.json +1 -1
  120. package/schemas/gui-helper.schema.json +1 -1
  121. package/schemas/gui-scenario.schema.json +189 -33
  122. package/schemas/helper-expansion-request.schema.json +44 -0
  123. package/schemas/helper-expansion-summary.schema.json +70 -0
  124. package/schemas/map-operation.schema.json +1 -1
  125. package/schemas/operation-result.schema.json +1 -1
  126. package/schemas/probability-analysis-result.schema.json +1 -1
  127. package/schemas/probability-compare-input.schema.json +1 -1
  128. package/schemas/probability-evaluate-input.schema.json +1 -1
  129. package/schemas/probability-inspect-input.schema.json +1 -1
  130. package/schemas/probability-render-input.schema.json +1 -1
  131. package/schemas/probability-scenario-set.schema.json +1 -1
  132. package/schemas/probability-sequence-input.schema.json +1 -1
  133. package/schemas/probability-simulate-input.schema.json +1 -1
  134. package/schemas/probability-sweep-input.schema.json +1 -1
  135. package/server.json +2 -2
package/docs/events.md CHANGED
@@ -6,7 +6,7 @@ Use the three event tools directly from the target mod.
6
6
 
7
7
  ## Inspect
8
8
 
9
- `hoi4.event_inspect` provides seven focused modes:
9
+ `hoi4.event_inspect` provides eight focused modes:
10
10
 
11
11
  - `scan`: inventory event definitions, namespaces, call sites, and unresolved references.
12
12
  - `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.
15
15
  - `state_flow`: report flags, variables, targets, scopes, and other tracked state read or changed along a route.
16
16
  - `lint`: find missing targets, unreachable events, suspicious cycles, conflicting definitions, invalid timing, and unresolved dynamic calls.
17
17
  - `impact`: identify callers, descendants, state dependencies, and files affected by a proposed event change.
18
+ - `helper_expansion`: stream bounded source-linked helper-call paths, dispatches, and state accesses with revision-bound continuation.
18
19
 
19
- 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.
20
+ Use narrow identifiers, direction, and depth limits when the task concerns one chain.
21
+ Broad scans build the structural event graph without expanding every scripted helper into duplicate paths.
22
+ Focused trace, path, and selector-based inventory requests may defer workspace-wide helper projections and lifecycle passes; their linked evidence records the partial boundary.
23
+ Focused trace and path calls collapse only the selected bounded route.
24
+ For a large helper closure, use [bounded helper expansion](helper-expansion.md) to receive resumable pages without first materializing every projection.
20
25
 
21
26
  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.
22
27
 
package/docs/gui.md CHANGED
@@ -41,7 +41,9 @@ Layout follows Clausewitz orientation and element-origin anchors, including `CEN
41
41
 
42
42
  Scripted-GUI composition follows `parent_scripted_gui` chains even when the linked child window is a top-level sibling in the `.gui` file. Literal `always = yes` and `always = no` visibility and click-enabled blocks are applied automatically. A scenario's `values` object supplies concrete runtime values in one place: variable names resolve numeric text, scripted-localisation names resolve dynamic labels, a progress-bar element name sets its fill value, and element keys ending in `.image`, `.frame`, `.x`, `.y`, `.visible`, or `.enabled` update that visual property. Scripted-GUI property expressions such as `image = "[GetMeterSprite]"` or `x = meter_fill_width` consume matching scenario values automatically. Dynamic text is parsed after scenario and scripted-localisation substitution, so a runtime string containing `£command_power` or `£[GetResourceIcon]` renders the resolved inline HOI4 text icon instead of literal marker text. Dynamic lists instantiate their declared `entry_container` or `country_scope_entry_container`; each scenario row can select the country template with `countryScope`, choose an explicit `entryContainer`, provide `countryTag` and `ideology` for `GetFlag`, and supply row-scoped text, image, frame, position, visibility, and enabled values. Masked country sprites use the actual mask and overlay dimensions, so custom flag sizes are discovered from GFX assets rather than assumed by the renderer.
43
43
 
44
- `hoi4.gui_inspect` and `hoi4.gui_render` generate a plausible seeded runtime scenario by default. The generator follows the complete `parent_scripted_gui` surface, discovers numeric and text tokens in GUI localisation and scripted-GUI properties, chooses real scripted-localisation text and sprite candidates, applies simple source thresholds, fills meters within their declared ranges, populates dynamic lists with coherent rows, selects one overlapping tab pane, keeps active and idle controls mutually exclusive, and leaves values explicitly supplied by the caller unchanged. Normal controls and animation frames remain stable unless variation is explicitly requested. Every explicit `relatedScenarios` entry is rendered beside the generated view.
44
+ `hoi4.gui_inspect` and `hoi4.gui_render` generate a seeded exploratory preview by default. The generator follows the complete `parent_scripted_gui` surface, discovers numeric and text tokens, fills meters within their declared ranges, and populates dynamic lists with coherent rows. Scripted-localisation text and sprite branches use the same structured condition evaluator as probability analysis, including compound conditions, inclusive comparisons, constants, declared scopes, and scripted triggers. An unknown earlier condition leaves the token unresolved instead of guessing a branch. The scenario's `conditionResults` records checked choices and missing inputs. Explicit values remain authoritative; generated inputs are not verified campaign state. Normal controls and animation frames remain stable unless variation is requested. Every explicit `relatedScenarios` entry is rendered beside the generated view.
45
+
46
+ Declare scoped facts with `scopes`, for example `"scopes": { "FROM": { "id": "target", "actor": "FRA", "state": { "support": 10 } } }`. Existing flat values such as `FROM.support` remain usable. Seeded pane and active/idle selection is exploratory layout sampling, not proof that every visibility branch is reachable.
45
47
 
46
48
  Generation is reproducible. Set `generatedScenarios.seed` to any stable string for an exact rerun, use `count` for several plausible versions, or configure numeric bounds, integer or decimal values, list row bounds, text samples, visibility probability, and state variation. Generated numeric values favour ordinary mid-range states, obey literal limits such as `[?capacity]/10`, keep displayed current/limit pairs coherent, and remain inside progress-bar ranges. The generated view is the default. Set `enabled` to `false` when only the supplied placeholder scenario should render, or set `preservePlaceholder` to `true` to include the placeholder beside generated scenarios.
47
49
 
@@ -0,0 +1,78 @@
1
+ # Bounded helper expansion
2
+
3
+ `hoi4.event_inspect` and `hoi4.tech_inspect` accept `mode: "helper_expansion"`.
4
+ This is a read-only stream of source-linked helper paths, not a source rewrite or runtime simulation.
5
+ It avoids materializing the whole helper closure before returning its first page.
6
+
7
+ Start either tool with:
8
+
9
+ ```json
10
+ {
11
+ "mode": "helper_expansion",
12
+ "helperExpansion": { "maxRecords": 250, "maxWork": 5000, "maxDepth": 64 }
13
+ }
14
+ ```
15
+
16
+ If `data.helperExpansion.finished` is false, pass its opaque `continuationUri` to the same tool:
17
+
18
+ ```json
19
+ {
20
+ "mode": "helper_expansion",
21
+ "helperExpansion": { "continuationUri": "<data.helperExpansion.continuationUri>" }
22
+ }
23
+ ```
24
+
25
+ The server restores root selection and depth from the continuation.
26
+ Page size and work limit may change between calls; root selection and depth may not.
27
+ A continuation may be used by a fresh server process with the same configured workspace, authorized principal, tool version, and exact source revision.
28
+ Every resume re-enumerates and verifies source bytes, even if `refresh` is omitted.
29
+ Changed source, domain, root topology, principal, or query is rejected explicitly rather than merged into earlier evidence.
30
+ To analyze edited source or use a different depth, start a new request without the continuation.
31
+
32
+ ## Bounds and evidence
33
+
34
+ `helperExpansion` has these optional fields:
35
+
36
+ | Field | Contract |
37
+ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
38
+ | `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. |
39
+ | `maxDepth` | 1–256 helper calls, default 64. |
40
+ | `maxRecords` | 1–5,000 records per page, default 250. |
41
+ | `maxWork` | 1–100,000 traversal transitions per page, default 5,000. |
42
+ | `continuationUri` | Opaque sibling resource returned in the prior tool result. Do not edit or construct it. |
43
+
44
+ Other inspection filters such as top-level `maxDepth`, `selector`, and `technologyId` are rejected in this mode rather than silently ignored.
45
+ The shared dependency inventory is limited to one million edges; source, parser, and artifact byte limits also remain enforced.
46
+ `maxWork` bounds dependency traversal, not the mandatory source scan or parsing.
47
+ An empty page can still advance work; continue when `finished` is false.
48
+
49
+ The linked JSON contains ordered `records` with `visit`, `terminal`, `cycle`, or `depth` kinds.
50
+ Each record links its root and exact edge-ID path to a page-local `edges` evidence table.
51
+ Event leaves include dispatches and helper-owned state accesses with their conditions, locations, and scope evidence.
52
+ Technology leaves include helper-owned grants, bonuses, and other technology references with source-linked call paths.
53
+ Different structural calls to the same helper remain distinct paths, including parallel calls under different conditions.
54
+ The technology call model links conditions through source locations; it does not evaluate or reconstruct runtime trigger outcomes.
55
+ Ordinary inspect modes remain the route for direct non-helper references and aggregate graph diagnostics.
56
+
57
+ `finished` means every selected root has been visited under the stated cycle and depth policy.
58
+ `complete` additionally requires complete source inventory and zero depth stops.
59
+ Cycles are reported and stopped at the repeated ancestor; completion describes finite simple-path coverage, not recursive execution.
60
+ Dynamic and missing source references remain unresolved findings, with exact counts and at most 100 samples in each page report.
61
+ Completion never establishes that those findings are resolved or that a runtime outcome is known.
62
+ 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.
63
+
64
+ The page report and its continuation are published together through the shared atomic artifact store.
65
+ The continuation is also linked as a sibling artifact; its resource URI is in the compact tool result, not reconstructed from a filename.
66
+ Cursor storage retains the active ancestor stack rather than completed paths.
67
+ Artifacts follow configured retention and admission limits; an evicted or unavailable cursor fails explicitly and requires a fresh analysis.
68
+ This is not permanent storage of every historical page.
69
+
70
+ ## Compatibility and boundaries
71
+
72
+ This opt-in mode and optional result summary are additive in 3.1.0.
73
+ Existing inspection modes retain their own ordering, representative-path policy, and materialization limits.
74
+ A depth- or projection-truncated materialized graph reports incomplete coverage.
75
+ The paged edge-path stream must not be mistaken for the deduplicated projections in those graphs.
76
+ Ordinary calls and persisted jobs return the same page contract.
77
+ Within-page work is bounded; the existing durable result checkpoint handles interruption after a page result has been staged.
78
+ Broader materialized-graph memory refinement remains separate from this bounded page contract.
package/docs/http.md CHANGED
@@ -10,6 +10,8 @@ JSON request bodies default to and are capped at 64 MiB, with a shared 128 MiB b
10
10
 
11
11
  `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.
12
12
 
13
+ 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.
14
+
13
15
  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.
14
16
 
15
17
  ## Loopback
package/docs/jobs.md ADDED
@@ -0,0 +1,85 @@
1
+ # Persistent jobs and MCP tasks
2
+
3
+ Long-running domain operations support optional MCP tasks while preserving the ordinary tool-call contract.
4
+ 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.
5
+ Clients that do not request a task continue to receive the same synchronous tool result as before.
6
+
7
+ 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.
8
+ Modern requests independently negotiate the Tasks extension, use authenticated flat handles, and receive terminal results in `tasks/get`.
9
+
10
+ Clients can request ordinary-call progress with a progress token.
11
+ Both protocol adapters share strictly increasing updates and bounded-frequency heartbeats, with cleanup when the request completes, fails, or is cancelled.
12
+ 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.
13
+ A modern native task handoff ends that request's heartbeat without declaring the underlying worker complete; clients retrieve ongoing status messages through `tasks/get`.
14
+
15
+ ## Supported tools
16
+
17
+ Optional tasks are available for every read-only event, technology, probability, map, GUI, and focus operation, and for the three rewrite tools:
18
+
19
+ - `hoi4.event_inspect`, `hoi4.event_render`, and `hoi4.event_compare`
20
+ - `hoi4.tech_inspect`, `hoi4.tech_render`, and `hoi4.tech_compare`
21
+ - `hoi4.probability_inspect`, `hoi4.probability_evaluate`, `hoi4.probability_sweep`, `hoi4.probability_simulate`, `hoi4.probability_sequence`, `hoi4.probability_compare`, and `hoi4.probability_render`
22
+ - `hoi4.map_inspect`, `hoi4.map_render`, and `hoi4.map_rewrite`
23
+ - `hoi4.gui_inspect`, `hoi4.gui_render`, and `hoi4.gui_rewrite`
24
+ - `hoi4.focus_inspect`, `hoi4.focus_render`, `hoi4.focus_raster`, and `hoi4.focus_rewrite`
25
+
26
+ Task results are exact tool results, including linked artifacts, partial-analysis markers, validation evidence, and tool-level errors.
27
+ A completed tool-level error is therefore a completed task whose result has `isError: true`; an execution or storage failure is a failed task.
28
+
29
+ ## Rewrite request keys
30
+
31
+ A native background rewrite must include a caller-generated `requestKey` between 1 and 256 characters.
32
+ Reuse the same key only for retries of the same rewrite request.
33
+ 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.
34
+ Do not reuse a key for a different tool in the same namespace.
35
+ 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.
36
+ Ordinary synchronous rewrite calls do not require `requestKey`.
37
+ An exact keyed retry after task visibility expires renews the task's polling window and retrieves the saved outcome without applying the rewrite again.
38
+ This also preserves failed and cancelled outcomes; a retry key cannot restart a terminal operation.
39
+ Both native and ordinary calls use that same receipt, while a conflicting retry or status lookup cannot extend its visibility.
40
+
41
+ The server binds an applied rewrite to its authenticated transaction journal before source replacement starts.
42
+ If execution stops after a commit, recovery reads that journal and reconstructs the domain result without planning or applying the rewrite again.
43
+ Blocked and unchanged plans do not bind a transaction because they never mutate source.
44
+
45
+ ## Cancellation and recovery
46
+
47
+ Cancellation is durable and cooperative.
48
+ A queued cancellation becomes terminal without starting source work.
49
+ 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.
50
+ Cancelling an ordinary synchronous call prevents admission when possible and otherwise requests cooperative cancellation of its durable job.
51
+ Closing the originating connection does not cancel an accepted native task.
52
+
53
+ Read-only jobs stage a source-revision-bound result checkpoint before terminal publication.
54
+ If a worker or server stops after that checkpoint, a later authorized process publishes the retained result without rerunning the operation.
55
+ Event and technology helper expansion also saves an authenticated intermediate frontier with its exact source revision and traversal contract.
56
+ A replacement validates the saved paths, adjacency cursor, graph identity, and checkpoint bytes before continuing.
57
+ Source changes before intermediate-frontier recovery cause a fresh analysis of the current revision; old and new graph evidence are never combined.
58
+ An active host allows at most two replacement attempts after proven worker death, and never retries the same unchanged frontier twice.
59
+ Checkpoint recovery never overrides cancellation or live/unverifiable ownership, and never replays a rewrite.
60
+ 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.
61
+ Their opt-in `helper_expansion` mode also returns [bounded continuation pages](helper-expansion.md) through both ordinary calls and persistent jobs.
62
+ 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.
63
+
64
+ Workers use fixed registered operations in separate Node.js processes.
65
+ Job records contain validated JSON inputs and authenticated state; they cannot select modules, executables, or arbitrary commands.
66
+ Workspace and principal authorization is rechecked for every submission, lookup, list, result retrieval, and cancellation.
67
+
68
+ ## Compatibility tools and retention
69
+
70
+ `hoi4.job_inspect` returns bounded status for an active, cancelled, or failed job and returns the original tool result for a completed job.
71
+ `hoi4.job_cancel` records an authorized cancellation request.
72
+ Both are control-plane operations and remain responsive while domain execution slots are occupied.
73
+ Both protocol adapters use the same control service, and these calls remain foreground operations even when a modern caller advertises the Tasks extension.
74
+ Job records are principal-private, including when another principal has access to the same workspace; this differs from artifacts shared within authorized workspace grants.
75
+
76
+ Native task identifiers include the workspace and persistent job identifier.
77
+ They are opaque client values; transaction identifiers and plan hashes are never public workflow inputs.
78
+ New persistent job IDs are derived from private server state, and earlier authenticated retry receipts remain usable without repeating their original operation.
79
+ 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.
80
+ Read-only terminal jobs follow the negotiated task retention period, clamped between one minute and seven days with a 24-hour default.
81
+ Mutation receipts remain durable after task visibility expires so a retry cannot duplicate an uncertain write.
82
+ Renewed task responses report their total lifetime from the original creation time, including elapsed age, while the newly granted visibility window remains bounded.
83
+
84
+ Persistent tasks require an operator-owned `serverStateRoot`.
85
+ HTTP principals can see only jobs within their existing workspace grants, and rewrite submission or cancellation also requires `hoi4:write`.
@@ -6,7 +6,7 @@ Use the three technology tools directly from the target mod.
6
6
 
7
7
  ## Inspect
8
8
 
9
- `hoi4.tech_inspect` provides eight focused modes:
9
+ `hoi4.tech_inspect` provides nine focused modes:
10
10
 
11
11
  - `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.
12
12
  - `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.
16
16
  - `bonus_coverage`: show which technologies or categories are covered by discovered research bonuses.
17
17
  - `lint`: filter source-linked findings by classification, diagnostic code, folder, or technology.
18
18
  - `impact`: find the definitions, placements, edges, grants, bonuses, unlocks, localisation, sprites, and files affected by a proposed removal or rename.
19
+ - `helper_expansion`: stream source-linked scripted-effect call paths and helper-owned technology references with bounded pages and revision-bound continuation.
19
20
 
20
21
  Example trace:
21
22
 
@@ -45,7 +46,10 @@ Impact mode takes a subject with `kind` set to `technology`, `category`, `folder
45
46
 
46
47
  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.
47
48
 
48
- 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.
49
+ Ordinary technology inspection uses the materialized graph and its explicit helper-depth and projection limits.
50
+ A truncated helper expansion reports incomplete coverage.
51
+ 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.
52
+ It preserves separate conditional call sites and identifies source, cycle, and depth boundaries without simulating trigger outcomes.
49
53
 
50
54
  ## Render
51
55
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "hoi4-agent-tools",
3
3
  "mcpName": "io.github.klimPaskov/hoi4-agent-tools",
4
- "version": "3.0.8",
4
+ "version": "3.1.0",
5
5
  "description": "Analyze HOI4 events, tech trees, AI weights, and MTTH; build focus trees, GUIs, and maps.",
6
6
  "type": "module",
7
7
  "license": "Apache-2.0",
@@ -47,6 +47,8 @@
47
47
  "docs/map.md",
48
48
  "docs/http.md",
49
49
  "docs/development.md",
50
+ "docs/jobs.md",
51
+ "docs/helper-expansion.md",
50
52
  "docs/images/readme/",
51
53
  "examples/clients/",
52
54
  "examples/probability/",
@@ -99,23 +101,27 @@
99
101
  },
100
102
  "dependencies": {
101
103
  "@fontsource-variable/roboto": "5.3.0",
104
+ "@modelcontextprotocol/core": "2.0.0",
105
+ "@modelcontextprotocol/node": "2.0.0",
102
106
  "@modelcontextprotocol/sdk": "1.30.0",
107
+ "@modelcontextprotocol/server": "2.0.0",
103
108
  "express": "5.2.1",
104
109
  "fast-glob": "3.3.3",
105
110
  "fontkit": "2.0.4",
106
111
  "iconv-lite": "0.7.3",
107
112
  "jose": "6.2.8",
108
- "sharp": "0.35.3",
113
+ "sharp": "0.35.4",
109
114
  "zod": "4.4.3"
110
115
  },
111
116
  "devDependencies": {
112
117
  "@eslint/js": "10.0.1",
118
+ "@modelcontextprotocol/client": "2.0.0",
113
119
  "@modelcontextprotocol/inspector": "2.1.0",
114
120
  "@types/express": "5.0.6",
115
121
  "@types/fontkit": "2.0.9",
116
122
  "@types/node": "22.20.1",
117
123
  "@types/pixelmatch": "5.2.6",
118
- "@vitest/coverage-v8": "4.1.10",
124
+ "@vitest/coverage-v8": "4.1.11",
119
125
  "ajv": "8.20.0",
120
126
  "ajv-formats": "3.0.1",
121
127
  "eslint": "10.8.1",
@@ -125,14 +131,14 @@
125
131
  "tsx": "4.23.11",
126
132
  "typescript": "6.0.3",
127
133
  "typescript-eslint": "8.66.0",
128
- "vitest": "4.1.10"
134
+ "vitest": "4.1.11"
129
135
  },
130
136
  "overrides": {
131
137
  "@hono/node-server": "2.1.0",
132
138
  "brace-expansion": "5.0.9",
133
139
  "fast-uri": "3.1.7",
134
140
  "qs": "6.16.0",
135
- "hono": "4.13.1",
141
+ "hono": "4.13.8",
136
142
  "nanoid": "3.3.18",
137
143
  "ip-address": "10.4.0",
138
144
  "postcss": "8.5.26",
@@ -1,5 +1,5 @@
1
1
  {
2
- "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.0.8/schemas/configuration.schema.json",
2
+ "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.1.0/schemas/configuration.schema.json",
3
3
  "$schema": "https://json-schema.org/draft/2020-12/schema",
4
4
  "type": "object",
5
5
  "properties": {
@@ -1,5 +1,5 @@
1
1
  {
2
- "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.0.8/schemas/continuous-focus-palette.schema.json",
2
+ "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.1.0/schemas/continuous-focus-palette.schema.json",
3
3
  "$schema": "https://json-schema.org/draft/2020-12/schema",
4
4
  "type": "object",
5
5
  "properties": {
@@ -1,5 +1,5 @@
1
1
  {
2
- "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.0.8/schemas/custom-weighted-pool.schema.json",
2
+ "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.1.0/schemas/custom-weighted-pool.schema.json",
3
3
  "$schema": "https://json-schema.org/draft/2020-12/schema",
4
4
  "type": "object",
5
5
  "properties": {
@@ -1,5 +1,5 @@
1
1
  {
2
- "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.0.8/schemas/event-feature-manifest.schema.json",
2
+ "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.1.0/schemas/event-feature-manifest.schema.json",
3
3
  "$schema": "https://json-schema.org/draft/2020-12/schema",
4
4
  "type": "object",
5
5
  "properties": {
@@ -1,5 +1,5 @@
1
1
  {
2
- "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.0.8/schemas/focus-plan.schema.json",
2
+ "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.1.0/schemas/focus-plan.schema.json",
3
3
  "$schema": "https://json-schema.org/draft/2020-12/schema",
4
4
  "type": "object",
5
5
  "properties": {
@@ -1,5 +1,5 @@
1
1
  {
2
- "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.0.8/schemas/focus-planning-sidecar.schema.json",
2
+ "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.1.0/schemas/focus-planning-sidecar.schema.json",
3
3
  "$schema": "https://json-schema.org/draft/2020-12/schema",
4
4
  "type": "object",
5
5
  "properties": {
@@ -1,5 +1,5 @@
1
1
  {
2
- "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.0.8/schemas/gui-animation-source.schema.json",
2
+ "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.1.0/schemas/gui-animation-source.schema.json",
3
3
  "$schema": "https://json-schema.org/draft/2020-12/schema",
4
4
  "type": "object",
5
5
  "properties": {
@@ -1,5 +1,5 @@
1
1
  {
2
- "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.0.8/schemas/gui-helper.schema.json",
2
+ "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.1.0/schemas/gui-helper.schema.json",
3
3
  "$schema": "https://json-schema.org/draft/2020-12/schema",
4
4
  "type": "object",
5
5
  "properties": {