hoi4-agent-tools 3.8.1 → 3.10.0

package/docs/gui.md

@@ -184,6 +184,31 @@ Source or scenario `enabled = false` selects disabled appearance and removes the
 
 The renderer does not run the game engine. Each render includes a fidelity report that separates fields it models from fields it approximates, ignores, cannot resolve, or does not support. Treat that report as part of the review.
 
+### Scenario fields
+
+Every `scenario` needs an `id`, a short label such as `"usa_1936"`. The other fields describe the game state the window is drawn under:
+
+| Field                                        | Meaning                                                                                                                                                                                        |
+| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `date`                                       | Game date, `"1936.1.1"`.                                                                                                                                                                       |
+| `controls`                                   | State controllers, `{"64": "GER"}`.                                                                                                                                                            |
+| `flags`                                      | Flags on the viewing country, `{"show_settings_page": true}`.                                                                                                                                  |
+| `closedFlags`                                | `true` treats every flag not listed in `flags` as unset, as on a country that never received it. Without it, an undeclared flag is unknown and every condition that reads it stays unresolved. |
+| `variables`                                  | Variables on the viewing country, `{"settings_page": 1}`.                                                                                                                                      |
+| `values`                                     | Exact runtime values for localisation tokens and scripted GUI properties, keyed as they appear in source.                                                                                      |
+| `visibility`                                 | Forced visibility by element or scripted GUI name, `{"settings_page_events": false}`; it overrides evaluated triggers.                                                                         |
+| `scopes`                                     | Named scope bindings such as `FROM` with their own state.                                                                                                                                      |
+| `resolution`, `uiScale`, `state`, `language` | Screen size, in-game UI scale, preview element state, and localisation language.                                                                                                               |
+| `background`                                 | `"transparent"` renders without the preview backdrop, so pixels the window does not cover are fully transparent in every PNG.                                                                  |
+
+A scripted GUI `visible` or `<element>_visible` trigger that the scenario decides hides or shows its element exactly.
+For compositing, each visible element is its own `<g>` group in the full SVG, with an `id` that matches the element in `layout.json`, which also records every element's box.
+A trigger the scenario cannot decide leaves the element drawn and lists it in the fidelity report as unresolved, so pages that the game shows one at a time can overlap in the preview.
+For tabbed windows, set the flags or variables of the page to show and `closedFlags: true`, then render each page as its own scenario through `relatedScenarios`.
+`GUI_UNRESOLVED_VISIBILITY_OVERLAP` names each overlapping pair drawn together for that reason.
+`GUI_NEAR_CENTRE_OFFSET` names an element whose horizontal centre is between half a pixel and 3 pixels from its parent's centre, which usually means it was meant to be centred.
+Scripted localisation (`defined_text`) used by the window resolves to its first branch whose trigger the scenario decides as true, as long as every earlier branch is decided false; otherwise the token renders as `[dynamic_loc]`. A value in `values` always takes precedence.
+
 The generated primary view replaces discovered numeric and text runtime tokens with plausible values. Set `generatedScenarios.preservePlaceholder` to `true`, or disable generation, when the same run should also show unresolved numeric values such as `[?variable|format]` as `[X]` and unresolved text-returning scripted or scoped localisation such as `[GetStatusText]`, `[FROM.GetName]`, and `[?leader_scope.GetName]` as `[dynamic_loc]`. Put `variable` or `GetStatusText` in the supplied scenario's `values` object when an exact value matters; explicit values always take precedence over generated ones and can drive the related meter or state-dependent controls. Supported HOI4 `§` localisation colour controls use the active font's palette and `§!` restores the face colour.
 
 A rewrite stops if malformed or unsupported GUI script makes the requested change ambiguous. Frame-sheet animation, nine-slice tiling, progress composition, masking, and the primary and secondary textures referenced by vanilla GFX definitions render offline. Font selection follows mod/game load order and preview language, accepts Paradox hex and numeric color declarations, and uses the supplied HOI4 bitmap or outline font assets without requiring host font installation. Shader operations outside the supported colour subset, hardcoded controls, and dynamic values that are not supplied by a scenario remain fidelity-report entries; an unexecuted shader never hides its resolved base texture.

package/docs/jobs.md

@@ -51,6 +51,14 @@ A running cancellation is observed by the isolated worker; if a rewrite has alre
 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.
 
+A worker busy in long synchronous analysis cannot observe its own cancellation, so the server that started it also supervises read-only jobs.
+A read-only job still running `jobCancelGraceSeconds` (default 10) after cancellation is stopped and settles as cancelled.
+A read-only job still running `jobDeadlineSeconds` (default 1,800) after it was dispatched is stopped and fails with `JOB_DEADLINE_EXCEEDED`; narrow its selector or limits, or raise the setting in the server configuration.
+Rewrite jobs are never stopped this way, because their transaction journal owns write recovery; they keep cooperative cancellation and reconciliation.
+Supervision belongs to the server process that dispatched the worker. A read-only worker whose dispatching server has exited enforces the same deadline itself and then exits; a rewrite worker keeps running until it finishes.
+`jobWorkerMaxHeapMiB` sets a V8 heap ceiling for each worker; without it, workers use Node's default.
+At most `maxSharedTools` (default 4) workers and expensive calls run at once across every server process that shares a `serverStateRoot`; further work waits for capacity.
+
 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.

package/docs/reference.md

@@ -21,6 +21,7 @@ Markdown headings and recognizable standalone names in generated `.log` files fo
 - When `hoi4.source_lookup` finds no definition, `suggestions` lists up to five indexed identifiers within three edits of the requested symbol, nearest first, which catches typos and near-miss names.
 - `hoi4.source_lookup` with `path` and `line` instead of `symbol` locates a source position, such as a diagnostic or a changed line in a diff. `path` may be a result path such as `mod:events/example.txt`, a path relative to a source root, or an absolute path inside one. The result names the file's layer and whether a later layer shadows it, the indexed definitions that contain the line, innermost first, and the chain of enclosing assignments with zero-based occurrences for repeated keys. Its `keyPath` starts inside the innermost definition: pass that definition's `id` as `symbol`, its `kind`, and the `keyPath` to read or list that exact block. Without `column`, the first non-blank character of the line is used. A file with parse errors returns its definitions but no structural chain. Only the requested file's folder is scanned, in every layer.
 - `hoi4.script_validate`: check a bounded effect or trigger body against installed native-command documentation. Supply the body in `source`, its `kind`, and its current `scope`. Results cover syntax, command kind, and declared scope, with exact documentation citations. They do not validate command parameters or prove game execution.
+- `hoi4.script_validate` with `path` instead of `source` checks a whole mod file: every effect and trigger body of an event, decision, national focus, scripted effect, scripted trigger, or on-action file, with the scope the file's structure fixes. It is meant to catch the game's own load errors before launch.
 
 ## Navigate a definition
 
@@ -58,6 +59,43 @@ It reads supported scopes from `effects_documentation.md`, `triggers_documentati
 `valid: true` applies only to `checksPerformed`; `parametersChecked` remains false.
 Inspect the cited parameter syntax and use the relevant domain tools for broader validation.
 Replies prioritize problems, bound `findings`, and report `omittedFindings`; execution is bounded to 256 visited entries and 64,000 UTF-8 source bytes.
+
+### Check a whole file
+
+Pass `path` (a result path, a path relative to a source root, or an absolute path inside one) without `source`, `kind`, `scope`, or `bindings`.
+The file's folder decides its family and root scopes: event `trigger`, `immediate`, `after`, and option bodies use the event type's scope; decision and focus triggers and effects use country scope; scripted effects, scripted triggers, on actions, and decision `target_trigger` bodies have no fixed scope, so their command kinds are checked and scope rules are skipped.
+`file` reports the family, the number of checked bodies, and how many had no fixed scope; a body without a fixed scope keeps `valid` at `null`.
+File mode lists only problems: matching commands are counted in `checkedCommands`, and unchecked native argument blocks are counted in `argumentBlocksUnchecked`.
+It is bounded to 50,000 visited entries.
+
+The mod's scripted effects and triggers count as known commands of their kind.
+Building, ideology, and resource names count as the documented generic triggers that take them as keys (`arms_factory > 2`, `communism > 0.4`), from the documentation's supported lists and from the `common/buildings`, `common/ideologies`, and `common/resources` databases of every source layer.
+`FROM`, chained keywords, `event_target:`, `var:`, `mio:`, and `sp:` blocks are checked for command kinds without scope rules.
+
+Two checks predict load errors the game reports:
+
+- `SCRIPT_DYNAMIC_VARIABLE_AS_TRIGGER`: a dynamic variable from `dynamic_variables_documentation.md` compared directly as a trigger, such as `num_owned_states > 1`; compare it with `check_variable` instead.
+- `SCRIPT_SCOPE_LINK_WRONG_SCOPE`: a scope link used outside the scopes the wiki's Scopes page allows, such as `controller` in country scope.
+
+The scope links `owner`, `controller`, `capital_scope`, `overlord`, and `faction_leader` are recognized in any letter case in both modes.
+
+### Player-facing text
+
+For event, decision, and national focus files, file mode also checks English text as the game resolves it, from the last loaded definition of each key, and adds `player_text` to `checksPerformed`.
+These findings have `status: "warning"` and never change `valid`:
+
+- `SCRIPT_NEWS_TEXT_COLOUR_CODE`: a news event, or an event with a `GFX_report_event` picture, whose title, description, or option text contains a `§` or `£` code, directly or through a `defined_text` branch it shows.
+- `SCRIPT_TEXT_IMPLEMENTATION_WORDING`: event text, or a decision's or focus's name or description, containing development wording such as TODO, placeholder, hardcoded, newly added, or reworked.
+- `SCRIPT_FLAG_TOOLTIP_UNLOCALISED`: a `has_country_flag`, `has_global_flag`, or `has_state_flag` check in a decision's `available` block or a focus's `available` or `bypass` block whose flag has no localisation key, so the requirement tooltip prints the raw flag name. Checks inside `hidden_trigger` and `custom_trigger_tooltip` are skipped, and scripted triggers called from those blocks are not expanded.
+
+Each message names the localisation file and line that carries the text.
+
+### Repeated event windows
+
+File mode reports `SCRIPT_EVENT_POPUP_REPEATED` warnings for any family and adds `event_popups` to `checksPerformed`.
+A visible event fired inside an `every_*` loop reaches one player once per loop member when it is sent to a fixed recipient (`ROOT`, `FROM`, `PREV`, `global`, a tag, an `event_target:` or a `var:` scope), or when it is `major = yes` without `fire_only_once`, because a major event is shown to every country.
+An event sent to each loop member in turn, a hidden event, and an event the scanned sources do not define are not reported.
+Scripted effects called inside a loop are checked in their own file, not followed from the caller.
 Search and context replies also report `limitedByBytes` when metadata exceeds their reply budget.
 Read omitted required sources with targeted calls rather than repeatedly requesting the same oversized bundle.
 Reference text supports UTF-8, Windows-1252, and explicitly BOM-marked UTF-16; native engine source encoding rules remain separate.

package/docs/setup.md

@@ -84,6 +84,17 @@ See [Local references](reference.md) for source selection and missing-source rep
 | A render lacks icons or fonts       | Confirm `--game-root` and the mod's asset paths. Read the missing-file findings.                                            |
 | A control's state is unresolved     | Supply the scenario's required country, state, controller or variable inputs; do not assume a visible control is available. |
 | A large query takes several minutes | Start with the specific tree, window or source area you need. Use [background jobs](jobs.md) when supported by your client. |
+| Idle server processes accumulate    | Set an idle limit as described in [Server lifetime](#server-lifetime).                                                      |
 
 The supplied Codex registration allows 120 seconds for startup and 600 seconds per tool call.
+
 For remote or shared deployments, use the [HTTP guide](http.md).
+
+### Server lifetime
+
+A stdio server exits when its client closes stdin, and when the process that launched it, such as a `cmd.exe` shim, has exited.
+Some clients start a server for every subagent and keep each connection open after the subagent finishes, so idle servers accumulate and each holds its own index in memory.
+A server with no client traffic and no open request for `stdioIdleExitMinutes` minutes exits.
+That setting applies to every client sharing the server configuration, so prefer the `HOI4_AGENT_STDIO_IDLE_EXIT_MINUTES` environment variable in the affected client's registration; the Codex registrations printed by `hoi4-agent-tools-setup --print-client-config` set it to 30.
+A client that later calls an exited server reports it as disconnected, so leave the limit at `0` (never) for a single long-lived session.
+Over stdio, read the `hoi4-agent://server/status` resource to see every server process that shares the server state root, with its transport, memory, last client activity and the execution limits in effect. Records of exited processes are removed on read; a server that has not updated its record for five minutes is listed as stale.

package/docs/tools.md

@@ -20,7 +20,7 @@ Use the connected server's live schema for the fields accepted by each call.
 | `hoi4.reference_search`     | Search local documentation in plain words or script names; each result names its answering line.                 |
 | `hoi4.reference_read`       | Read one revision-bound section, with line continuation.                                                         |
 | `hoi4.source_lookup`        | Find exact definitions, overrides and usages across game, DLC and mod, or the definition containing a file line. |
-| `hoi4.script_validate`      | Check snippet syntax, native command kinds, and declared scopes against local documentation.                     |
+| `hoi4.script_validate`      | Check a snippet or a whole mod file for syntax, command kinds, and scopes against local documentation.           |
 | `hoi4.event_inspect`        | Scan, trace, explain, lint, or assess event chains and their state flow.                                         |
 | `hoi4.event_render`         | Render source-linked event routes, options, timing, state, scope, and unresolved edges.                          |
 | `hoi4.event_compare`        | Compare event-chain topology and diagnostics between revisions.                                                  |

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "hoi4-agent-tools",
-  "version": "3.8.1",
+  "version": "3.10.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "hoi4-agent-tools",
-      "version": "3.8.1",
+      "version": "3.10.0",
       "license": "Apache-2.0",
       "dependencies": {
         "@fontsource-variable/roboto": "5.3.0",
@@ -5744,9 +5744,9 @@
       "license": "MIT"
     },
     "node_modules/proxy-addr": {
-      "version": "2.0.7",
-      "resolved": "https://registry.npmjs.org/proxy-addr/-/proxy-addr-2.0.7.tgz",
-      "integrity": "sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg==",
+      "version": "2.0.8",
+      "resolved": "https://registry.npmjs.org/proxy-addr/-/proxy-addr-2.0.8.tgz",
+      "integrity": "sha512-5nnx0yGyVUcY6t9RnWcARWtwT9F1D8O9rt08htPvnd49W1IgZtmLkhu9WfMzQj1cFxjHIO6connUNVW5k7AVyQ==",
       "license": "MIT",
       "dependencies": {
         "forwarded": "0.2.0",
@@ -5754,6 +5754,10 @@
       },
       "engines": {
         "node": ">= 0.10"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
       }
     },
     "node_modules/punycode": {
@@ -6256,9 +6260,9 @@
       }
     },
     "node_modules/source-map-js": {
-      "version": "1.2.1",
-      "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
-      "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==",
+      "version": "1.2.2",
+      "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.2.tgz",
+      "integrity": "sha512-KGj/8Y43x35aZVDtt+J4mK1hoLGHULMYfSkODJNQjNDC3oW1PqPoxMwo0pLUsWM/UEGzON/NxeHywEfNXNP3Vw==",
       "dev": true,
       "license": "BSD-3-Clause",
       "engines": {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hoi4-agent-tools",
   "mcpName": "io.github.klimPaskov/hoi4-agent-tools",
-  "version": "3.8.1",
+  "version": "3.10.0",
   "description": "HOI4 modding tools for agents: local references, visual previews, focus trees, interfaces and maps.",
   "type": "module",
   "license": "Apache-2.0",