hoi4-agent-tools 3.0.9 → 3.2.0

package/CHANGELOG.md

@@ -2,7 +2,38 @@
 
 ## Unreleased
 
-No unreleased changes.
+## 3.2.0 - 2026-09-20
+
+- Add read-only `hoi4.impact_inspect` with active and overridden definitions, direct and transitive source consumers, state-key access roles, cycle and coverage evidence, and in-memory source comparisons.
+- Connect event, focus, decision, idea, technology, scripted-helper, localisation, scripted-GUI, GUI, sprite, and texture references where typed static source evidence supports an edge; leave dynamic and unsupported references unresolved.
+- Identify affected declared scenario-suite cases from bounded workspace-owned JSON references without executing them.
+- Add read-only `hoi4.decision_inspect` for decision and mission inventory, declared actor and target gates, costs and direct payments, lifecycle paths, and scenario-by-scenario source comparisons.
+- Reuse the probability adapters for decision and mission AI scores and score comparisons, retaining linked traces and explicit proposal limits.
+- Serve both tools through ordinary and persistent native MCP tasks over legacy and modern stdio and HTTP routes, with revision-bound linked reports and source-preserving overlays.
+
+## 3.1.0 - 2026-09-20
+
+- Reuse authenticated content-addressed parsed documents and file-local index segments across authorized local processes while revalidating current source bytes, load order, shadowing, workspace topology, and principal scope.
+- Rebuild exact indexes from immutable segments, retain typed reverse source dependencies, and heal malformed or tampered persistent cache entries without trusting timestamps or file sizes.
+- Run event, technology, probability, map, GUI, and focus analysis in fixed-entry isolated workers backed by durable authenticated jobs, revision-fenced ownership, bounded retention, and source-revision result checkpoints.
+- Advertise optional negotiated MCP tasks for all long-running domain calls while preserving exact ordinary-call results, progress, cancellation, linked resources, tool errors, and both stdio and HTTP compatibility.
+- Share task execution, authorization, and all 23 domain tool definitions with an MCP 2026-07-28 Tasks extension adapter, routed by production stdio and authenticated HTTP entry points.
+- Share `hoi4.job_inspect` and `hoi4.job_cancel` between protocol adapters as responsive, principal-private compatibility controls that remain available while domain execution slots are occupied.
+- Share the bounded probability-analysis prompt metadata and body between protocol adapters without starting jobs or source analysis.
+- Advertise the same server instructions through legacy initialization and modern discovery.
+- Deliver opt-in modern request progress through the SDK's related-notification API, preserving ordered heartbeats and cancellation over connection and auto-streaming production HTTP serving.
+- Pin each bounded stdio connection to its opening protocol era and route authenticated modern HTTP claims through strict SDK validation without changing legacy stateful sessions or the existing request-security gates.
+- Share the two opt-in ChaosX private-tool implementations between stdio protocol generations while keeping them absent from ordinary and HTTP catalogs.
+- Pin patched Sharp, Hono, Vitest, and coverage packages while retaining the exact dependency graph in the lockfile.
+- Require caller-stable request keys for native background focus, GUI, and map rewrites; deduplicate exact retries independently of polling hints and reject conflicting reuse.
+- Derive new job IDs from private server state, preserve authenticated earlier retry receipts without replay, and authenticate modern task handles before execution admission or cancellation.
+- Renew only task-visibility metadata for exact retries of expired rewrite receipts, preserving terminal outcomes and source edits through native and ordinary calls in both protocol generations.
+- Share bounded artifact-resource reads between protocol generations, including exact byte ranges, continuation links, manifest projection, and workspace-grant checks.
+- Bind rewrite transactions and domain completion recipes before source application, reconcile stopped workers without replanning, and retain post-write validation artifacts without changing immutable plan hashes.
+- Retain revision-addressed event and technology graphs for comparisons after process restart, and preserve explicit helper, source, candidate, node, edge, and render coverage boundaries.
+- Add opt-in bounded `helper_expansion` pages for event and technology inspection, preserving distinct source call paths and resumable principal- and revision-bound cursors without retaining completed traversal history.
+- Mark depth- and projection-truncated materialized helper graphs incomplete, and retain explicit cycle, dynamic-reference, source-coverage, and page-retention boundaries.
+- Harden Windows atomic job publication, bounded pre-dispatch worker-lease transfer retries, disconnect recovery, principal isolation, task expiry, and mutation-receipt retention under concurrent clients.
 
 ## 3.0.9 - 2026-09-08
 

package/README.md

@@ -1,6 +1,6 @@
 # HOI4 Agent Tools
 
-HOI4 Agent Tools is an MCP server for coding agents to understand Hearts of Iron IV event chains, technology systems, AI weights, and MTTH timing and to inspect, create, or clean up focus trees, scripted GUIs, and maps. It produces source-linked structural and visual evidence that agents can use inside a larger modding workflow.
+HOI4 Agent Tools is an MCP server for coding agents to understand Hearts of Iron IV event chains, decisions, cross-system dependencies, technology systems, AI weights, and MTTH timing and to inspect, create, or clean up focus trees, scripted GUIs, and maps. It produces source-linked structural and visual evidence that agents can use inside a larger modding workflow.
 
 ## What it does
 
@@ -8,6 +8,7 @@ HOI4 Agent Tools is an MCP server for coding agents to understand Hearts of Iron
 - Scripted GUIs: trace GUI, GFX, scripted-GUI, and localisation links; render value-driven variants, dynamic country flags, inline text icons, states, resolutions, hierarchy, and click regions; diagnose alignment, visibility, clipping, panel containment, and button-label centering; create or repair interface source.
 - Maps: navigate the complete rendered map by ID or localised name; inspect provinces, states, regions, adjacency, supply, railways, and positions; create states and provinces; change IDs; and repair connected map data.
 - Event chains: scan definitions and call sites, trace routes and state flow, lint references, render graphs, and compare revisions without editing event source.
+- Cross-system impact and decisions: trace definitions and consumers across source systems, evaluate declared actor and target scenarios, inspect costs and mission paths, and compare in-memory proposals.
 - Technology trees: reconstruct technology and doctrine paths, folder layouts, unlocks, bonuses, grants, metadata, assets, and structural changes.
 - AI and MTTH: evaluate weighted choices and timing across explicit scenarios, bind special scope chains, enumerate dynamic target pools, sweep uncertain inputs, simulate distributions, compare patches, and analyze declared stateful pools.
 
@@ -71,6 +72,10 @@ On non-Windows systems, use `hoi4-agent-tools` as the command. Agentic HOI4 repo
 | `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.                           |
+| `hoi4.impact_inspect`       | Trace symbol and changed-file consumers across source systems and compare proposals.      |
+| `hoi4.decision_inspect`     | Inventory and evaluate decisions or missions under declared scenarios and source changes. |
+| `hoi4.job_inspect`          | Inspect durable background work or retrieve its completed tool result.                    |
+| `hoi4.job_cancel`           | Durably request cancellation of authorized background work.                               |
 | `hoi4.tech_inspect`         | Scan, trace, explain, lint, and assess technology and doctrine systems.                   |
 | `hoi4.tech_render`          | Render source layouts with real item sizes and year guides, plus dependencies and assets. |
 | `hoi4.tech_compare`         | Compare technology graphs, placements, references, diagnostics, and source overlays.      |
@@ -86,11 +91,13 @@ Set `HOI4_AGENT_TOOLS_CHAOSX=1` on the server process to expose the optional `ch
 
 Large outputs are linked `hoi4-agent://` resources. For resources over 1 MiB, follow the `continuationUri` returned in `_meta` until it is `null`; clients may also request byte ranges with `?offset=<bytes>&length=<bytes>`.
 
+Long-running domain calls advertise optional MCP task support. A task survives client disconnects and can be retrieved after reconnect; clients without task support keep the ordinary synchronous result contract. Native background rewrites require a stable caller-supplied `requestKey` so retries resolve to one durable mutation receipt. See [Persistent jobs and MCP tasks](docs/jobs.md).
+
 ## Coexistence with agent workflows
 
 HOI4 Agent Tools provides HOI4 domain operations without replacing repository instructions such as `AGENTS.md`, skills, plans, or subagents. Its optional weighted-logic prompt helps an agent scope one probability analysis and then returns control to the normal workflow.
 
-Connecting and listing tools does not scan mod source. Compact tool schemas and linked resources keep large diagnostics, renders, and diffs out of the agent's working context until needed. Event, technology, and probability tools analyze source without editing it; only `hoi4.*_rewrite` calls edit mod source.
+Connecting and listing tools does not scan mod source. Compact tool schemas and linked resources keep large diagnostics, renders, and diffs out of the agent's working context until needed. Event, impact, decision, technology, and probability tools analyze source without editing it; only `hoi4.*_rewrite` calls edit mod source.
 
 ## Create or clean content
 
@@ -100,6 +107,7 @@ Ask your agent in normal task language. A typical workflow is inspect, render, r
 - Scripted GUIs: "Create a scripted GUI for this mechanic," or "Render every value-driven version of this window and fix hidden controls, off-center button text, background alignment, clipping, and click-region conflicts." See [Scripted GUIs](docs/gui.md).
 - Maps: "Render the whole map and find this state by name," "Create a state from these provinces," "Create a province inside this exact rectangle," or "Swap these state IDs and update connected references." See [Maps](docs/map.md).
 - Event chains: "Trace every route from this event and explain where its flags and variables change," or "Compare the workspace event graph with its previous revision and render the affected routes." See [Event chains](docs/events.md).
+- Cross-system impact and decisions: "Find every direct and transitive consumer of this idea," or "Compare who can take this decision, what they pay, and its mission end paths for these actor and target scenarios." See [Cross-system impact and decisions](docs/analysis.md).
 - Technology trees: "Explain everything this technology requires and unlocks," or "Compare this technology patch and render every affected folder and doctrine branch." See [Technology trees](docs/technology.md).
 - AI and MTTH: "Compare these focus weights across peace, defensive-war, and low-stability scenarios," or "Show when this MTTH event becomes likely and which unknown inputs control the result." See [AI and MTTH analysis](docs/probability.md).
 

package/dist/bin/stdio.js

@@ -1,18 +1,14 @@
 #!/usr/bin/env node
 import { canonicalJson } from '../hoi4_agent_tools/core/canonical.js';
-import { createMcpServer } from '../hoi4_agent_tools/mcp/server/create.js';
-import { BoundedStdioServerTransport, StdioFrameLimitError, StdioInvalidMessageError, StdioInvalidUtf8Error, } from '../hoi4_agent_tools/mcp/transports/bounded-stdio.js';
-import { FinalProtocolTransport } from '../hoi4_agent_tools/mcp/transports/protocol-gate.js';
+import { StdioFrameLimitError, StdioInvalidMessageError, StdioInvalidUtf8Error, } from '../hoi4_agent_tools/mcp/transports/bounded-stdio.js';
+import { serveNegotiatedStdio } from '../hoi4_agent_tools/mcp/transports/negotiated-stdio.js';
 import { createEngine } from '../hoi4_agent_tools/runtime.js';
 async function main() {
     const engine = await createEngine();
-    const context = {};
-    const server = createMcpServer(engine, context);
-    if (process.env.HOI4_AGENT_TOOLS_CHAOSX === '1') {
-        const { registerChaosxTools } = await import('../hoi4_agent_tools/mcp/tools/chaosx.js');
-        registerChaosxTools(server, engine, context);
-    }
-    server.server.onerror = (error) => {
+    const chaosxTools = process.env.HOI4_AGENT_TOOLS_CHAOSX === '1'
+        ? await import('../hoi4_agent_tools/mcp/tools/chaosx.js')
+        : undefined;
+    const onerror = (error) => {
         const fatalInputError = error instanceof StdioFrameLimitError || error instanceof StdioInvalidUtf8Error;
         const rejectedMessage = error instanceof StdioInvalidMessageError;
         if (fatalInputError)
@@ -24,8 +20,23 @@ async function main() {
             message: error.message,
         })}\n`);
     };
-    const transport = new BoundedStdioServerTransport();
-    await server.connect(new FinalProtocolTransport(transport));
+    await serveNegotiatedStdio(engine, {
+        onerror,
+        onFailure: (error) => {
+            process.exitCode = 1;
+            process.stderr.write(`${canonicalJson({
+                level: 'error',
+                event: 'transport_startup_failed',
+                message: error instanceof Error ? error.message : String(error),
+            })}\n`);
+        },
+        ...(chaosxTools === undefined
+            ? {}
+            : {
+                createModernPrivateTools: chaosxTools.createChaosxToolOperations,
+                registerLegacy: (server) => chaosxTools.registerChaosxTools(server, engine, {}),
+            }),
+    });
 }
 main().catch((error) => {
     process.stderr.write(`${canonicalJson({

package/dist/hoi4_agent_tools/core/analysis-checkpoints.js

@@ -0,0 +1,82 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { z } from 'zod/v4';
+import { canonicalJson, hashCanonical } from './canonical.js';
+import { ServiceError } from './result.js';
+import { PACKAGE_VERSION } from '../version.js';
+const digest = z.string().regex(/^[a-f0-9]{64}$/u);
+const envelopeSchema = z
+    .object({
+    version: z.literal(1),
+    key: digest,
+    sourceRevision: digest,
+    state: z.json(),
+})
+    .strict();
+const active = new AsyncLocalStorage();
+/** Internal typed execution context; no transport or caller-supplied executable hooks. */
+export function withAnalysisCheckpoints(checkpoints, run) {
+    return active.run(checkpoints, run);
+}
+export function currentAnalysisCheckpoints() {
+    return active.getStore();
+}
+/** The authenticated job record commits to the exact immutable checkpoint bytes. */
+export function jobAnalysisCheckpoints(context) {
+    let checkpoint = context.checkpoint;
+    const workspace = context.engine.resolver.get(context.workspaceId, context.principal);
+    return {
+        async load(key, sourceRevision, schema) {
+            if (checkpoint?.cursor !== `analysis:${key}` || checkpoint.sourceRevision !== sourceRevision)
+                return undefined;
+            if (checkpoint.resourceUri === undefined || checkpoint.stateHash === undefined)
+                throw new ServiceError('ANALYSIS_CHECKPOINT_INVALID', 'Analysis checkpoint has no authenticated state');
+            const resource = await context.engine.artifacts.readLogical(workspace, checkpoint.resourceUri, {
+                mimeType: 'application/json',
+                maxBytes: 268_435_456,
+                maxChunks: 256,
+            }, context.signal);
+            const envelope = envelopeSchema.parse(JSON.parse(resource.bytes.toString('utf8')));
+            if (envelope.key !== key ||
+                envelope.sourceRevision !== sourceRevision ||
+                hashCanonical(envelope) !== checkpoint.stateHash)
+                throw new ServiceError('ANALYSIS_CHECKPOINT_INVALID', 'Analysis checkpoint identity or content does not match its job');
+            return schema.parse(envelope.state);
+        },
+        async save(key, sourceRevision, state, completed, total) {
+            context.signal.throwIfAborted();
+            const envelope = envelopeSchema.parse({ version: 1, key, sourceRevision, state });
+            await context.engine.artifacts.withAtomicChunkedWrites(workspace, [
+                {
+                    name: 'analysis-checkpoint.json',
+                    mimeType: 'application/json',
+                    content: canonicalJson(envelope),
+                    provenance: {
+                        kind: 'analysis-checkpoint',
+                        toolVersion: PACKAGE_VERSION,
+                        schemaVersion: '1',
+                        sourceHashes: {},
+                        metadata: { key, sourceRevision },
+                    },
+                    description: 'Revision-bound internal dependency-expansion checkpoint',
+                },
+            ], async ([resource], physical) => {
+                const next = {
+                    sourceRevision,
+                    resourceUri: resource.uri,
+                    cursor: `analysis:${key}`,
+                    stateHash: hashCanonical(envelope),
+                    resources: physical.map(({ uri }) => uri),
+                };
+                // Publish the authenticated pin before releasing artifact admission. A competing
+                // writer therefore sees either the old complete checkpoint or the new one.
+                await context.saveCheckpoint(next);
+                checkpoint = next;
+            }, context.signal);
+            await context.progress({
+                completed,
+                total,
+                message: 'Expanding source-bound helper dependencies',
+            });
+        },
+    };
+}

package/dist/hoi4_agent_tools/core/analysis-evidence.js

@@ -0,0 +1,9 @@
+import { boundedSourceHashEvidence } from './artifacts.js';
+/** Bind a linked analysis report to every source in both compared revisions. */
+export function analysisSourceEvidence(before, after, additionalSources = {}) {
+    return boundedSourceHashEvidence(Object.fromEntries([
+        ...before.files.map((file) => [`before:${file.displayPath}`, file.sha256]),
+        ...(after?.files.map((file) => [`after:${file.displayPath}`, file.sha256]) ?? []),
+        ...Object.entries(additionalSources),
+    ]));
+}

package/dist/hoi4_agent_tools/core/analysis-job-operations.js

@@ -0,0 +1,38 @@
+import { z } from 'zod/v4';
+import { DecisionAnalyzer } from '../decision/service.js';
+import { ImpactAnalyzer } from '../impact/service.js';
+import { decisionInspectRequestSchema, impactInspectRequestSchema } from '../schemas/analysis.js';
+import { errorResult, toolResult } from './operation-result.js';
+import { ServiceError } from './result.js';
+const wireResult = z.record(z.string(), z.json());
+/** Registers the two read-only analysis services for durable ordinary and native tasks. */
+export function registerAnalysisJobs(operations, engine) {
+    const impact = new ImpactAnalyzer(engine);
+    const decision = new DecisionAnalyzer(engine);
+    const register = (name, schema, execute, progressMessage) => {
+        operations.registerRead(name, schema, async (input, context) => {
+            try {
+                if (input.workspaceId !== 'current' && input.workspaceId !== context.workspaceId)
+                    throw new ServiceError('JOB_ARGUMENT_SCOPE_MISMATCH', 'The request workspace does not match the authorized job workspace');
+                await context.progress({ completed: 0, total: 2, message: progressMessage });
+                const result = await execute({
+                    ...input,
+                    workspaceId: context.workspaceId,
+                    ...(context.principal === undefined ? {} : { principal: context.principal }),
+                    signal: context.signal,
+                });
+                await context.progress({ completed: 2, total: 2, message: 'Analysis complete' });
+                const wire = wireResult.parse(JSON.parse(JSON.stringify(toolResult(result))));
+                await context.stageResult(wire, { sourceRevision: result.data.sourceRevision });
+                return wire;
+            }
+            catch (error) {
+                if (context.signal.aborted)
+                    throw error;
+                return wireResult.parse(JSON.parse(JSON.stringify(errorResult(error, context.workspaceId))));
+            }
+        });
+    };
+    register('hoi4.impact_inspect', impactInspectRequestSchema, (input) => impact.inspect(input), 'Tracing cross-system impact');
+    register('hoi4.decision_inspect', decisionInspectRequestSchema, (input) => decision.inspect(input), 'Analyzing decisions and missions');
+}

package/dist/hoi4_agent_tools/core/artifact-resource.js

@@ -0,0 +1,173 @@
+import { canonicalJson } from './canonical.js';
+import { ServiceError } from './result.js';
+const artifactResourceLimit = 1_048_576;
+const artifactChunkMetadataKey = 'io.github.klimpaskov/hoi4-agent-tools.artifact-byte-range';
+const fatalUtf8Decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+export const artifactResourceDefinition = {
+    name: 'artifact',
+    uriTemplate: 'hoi4-agent://workspace/{workspaceId}/artifact/{sha256}/{provenanceHash}/{name}',
+    title: 'HOI4 review artifact',
+    description: 'Complete plans, diagnostics, layouts, previews, event graphs, routes, state and scope reports, comparisons, and diffs. Reads accept zero-based byte offset and positive byte length query selectors; each response reports its exact byte range and continuation URI in _meta.',
+    _meta: {
+        [artifactChunkMetadataKey]: {
+            version: 1,
+            unit: 'byte',
+            maxChunkSize: artifactResourceLimit,
+            selectors: {
+                offset: { type: 'integer', minimum: 0, default: 0 },
+                length: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: artifactResourceLimit,
+                    default: artifactResourceLimit,
+                },
+                metadata: { type: 'string', enum: ['manifest'], optional: true },
+            },
+        },
+    },
+};
+function assertResourceSelectors(uri, allowed) {
+    if (uri.hash !== '' || uri.username !== '' || uri.password !== '' || uri.port !== '') {
+        throw new ServiceError('RESOURCE_URI_INVALID', 'Resource URI is not canonical');
+    }
+    const allowedNames = new Set(allowed);
+    const seen = new Set();
+    for (const name of uri.searchParams.keys()) {
+        if (!allowedNames.has(name)) {
+            throw new ServiceError('RESOURCE_SELECTOR_INVALID', 'Resource selector is not supported');
+        }
+        if (seen.has(name)) {
+            throw new ServiceError('RESOURCE_SELECTOR_INVALID', 'Resource selectors may not be repeated');
+        }
+        seen.add(name);
+    }
+}
+function contentArtifactUri(uri) {
+    const contentUri = new URL(uri);
+    contentUri.search = '';
+    contentUri.hash = '';
+    return contentUri.href;
+}
+function exactUtf8Text(bytes) {
+    try {
+        const text = fatalUtf8Decoder.decode(bytes);
+        return Buffer.from(text, 'utf8').equals(bytes) ? text : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function artifactRangeParameter(uri, name, fallback, minimum, maximum = Number.MAX_SAFE_INTEGER) {
+    const raw = uri.searchParams.get(name);
+    if (raw === null)
+        return fallback;
+    if (!/^\d+$/u.test(raw)) {
+        throw new ServiceError('ARTIFACT_RANGE_INVALID', 'Artifact byte range is invalid');
+    }
+    const value = Number(raw);
+    if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+        throw new ServiceError('ARTIFACT_RANGE_INVALID', 'Artifact byte range is invalid');
+    }
+    return value;
+}
+function artifactChunkMetadata(uri, metadata, totalSize, offset, returnedLength, requestedLength) {
+    const endExclusive = offset + returnedLength;
+    let continuationUri = null;
+    if (endExclusive < totalSize) {
+        const continuation = new URL(contentArtifactUri(uri));
+        continuation.searchParams.set('offset', String(endExclusive));
+        continuation.searchParams.set('length', String(requestedLength));
+        if (metadata !== null)
+            continuation.searchParams.set('metadata', metadata);
+        continuationUri = continuation.href;
+    }
+    return {
+        [artifactChunkMetadataKey]: {
+            version: 1,
+            unit: 'byte',
+            totalSize,
+            returnedRange: { offset, length: returnedLength, endExclusive },
+            complete: offset === 0 && returnedLength === totalSize,
+            continuationUri,
+        },
+    };
+}
+/** Shared bounded resource reader. URI ownership never supplies a principal or root grant. */
+export async function readArtifactResource(engine, uriInput, context, signal) {
+    signal.throwIfAborted();
+    let uri;
+    let workspaceId;
+    try {
+        if (uriInput.length > 8192)
+            throw new Error('URI exceeds the resource limit');
+        uri = new URL(uriInput);
+        const segments = uri.pathname.split('/');
+        if (uri.protocol !== 'hoi4-agent:' ||
+            uri.hostname !== 'workspace' ||
+            segments.length !== 6 ||
+            segments[0] !== '' ||
+            segments[2] !== 'artifact' ||
+            segments.some((segment, index) => index !== 0 && segment === ''))
+            throw new Error('Invalid resource path');
+        workspaceId = decodeURIComponent(segments[1]);
+    }
+    catch {
+        throw new ServiceError('RESOURCE_URI_INVALID', 'Resource URI is invalid');
+    }
+    signal.throwIfAborted();
+    assertResourceSelectors(uri, ['offset', 'length', 'metadata']);
+    const workspace = engine.resolver.get(workspaceId, context.principal);
+    const offset = artifactRangeParameter(uri, 'offset', 0, 0);
+    const length = artifactRangeParameter(uri, 'length', artifactResourceLimit, 1, artifactResourceLimit);
+    const metadata = uri.searchParams.get('metadata');
+    if (metadata !== null && metadata !== 'manifest') {
+        throw new ServiceError('ARTIFACT_METADATA_INVALID', 'Artifact metadata selector is invalid');
+    }
+    if (metadata === 'manifest') {
+        const described = await engine.artifacts.describe(workspace, contentArtifactUri(uri), signal);
+        const { path: artifactPath, ...publicManifest } = described;
+        void artifactPath;
+        const manifestBytes = Buffer.from(`${canonicalJson(publicManifest)}\n`, 'utf8');
+        const start = Math.min(offset, manifestBytes.length);
+        const selected = manifestBytes.subarray(start, Math.min(manifestBytes.length, start + length));
+        const complete = start === 0 && selected.length === manifestBytes.length;
+        const _meta = artifactChunkMetadata(uri, metadata, manifestBytes.length, start, selected.length, length);
+        return {
+            contents: [
+                complete
+                    ? {
+                        uri: uri.href,
+                        mimeType: 'application/json',
+                        text: selected.toString('utf8'),
+                        _meta,
+                    }
+                    : {
+                        uri: uri.href,
+                        mimeType: 'application/json',
+                        blob: selected.toString('base64'),
+                        _meta,
+                    },
+            ],
+        };
+    }
+    const artifact = await engine.artifacts.read(workspace, contentArtifactUri(uri), { offset, length }, signal);
+    const textual = artifact.mimeType.startsWith('text/') ||
+        artifact.mimeType === 'application/json' ||
+        artifact.mimeType === 'image/svg+xml';
+    const start = Math.min(offset, artifact.totalSize);
+    const complete = start === 0 && artifact.bytes.length === artifact.totalSize;
+    const text = textual && complete ? exactUtf8Text(artifact.bytes) : undefined;
+    const _meta = artifactChunkMetadata(uri, metadata, artifact.totalSize, start, artifact.bytes.length, length);
+    return {
+        contents: [
+            text !== undefined
+                ? { uri: uri.href, mimeType: artifact.mimeType, text, _meta }
+                : {
+                    uri: uri.href,
+                    mimeType: artifact.mimeType,
+                    blob: artifact.bytes.toString('base64'),
+                    _meta,
+                },
+        ],
+    };
+}

package/dist/hoi4_agent_tools/core/artifacts.js

@@ -707,17 +707,27 @@ export class ArtifactStore {
     maxBytes;
     maxEntries;
     maxSingleBytes;
+    retention;
     #verifiedContent = new Map();
-    constructor(maxBytes = 536_870_912, maxEntries = 5_000, maxSingleBytes = 134_217_728) {
+    constructor(maxBytes = 536_870_912, maxEntries = 5_000, maxSingleBytes = 134_217_728, retention) {
         this.maxBytes = maxBytes;
         this.maxEntries = maxEntries;
         this.maxSingleBytes = maxSingleBytes;
+        this.retention = retention;
     }
     async pruneForAdmission(workspace, usage, additionalBytes, additionalEntries, protectedManifests, protectedTargets, signal) {
         if (usage.entries + additionalEntries <= this.maxEntries &&
             usage.bytes <= this.maxBytes - additionalBytes) {
             return usage;
         }
+        // Read durable pins while holding the same cross-process publication lock used by
+        // checkpoint commits. A committed frontier cannot disappear between save and resume.
+        for (const uri of (await this.retention?.(workspace, signal)) ?? []) {
+            signal?.throwIfAborted();
+            const { sha256, provenanceHash, name } = this.parseUri(workspace, uri);
+            protectedTargets.add(await containedGeneratedPath(workspace.artifactRoot, sha256.slice(0, 2), sha256, name));
+            protectedManifests.add(await containedGeneratedPath(workspace.artifactRoot, sha256.slice(0, 2), sha256, `${name}.${provenanceHash}.manifest.json`));
+        }
         // Reclaim to a low-water mark so a busy agent workflow does not rescan and evict one artifact
         // for every subsequent tool call. The incoming batch itself remains protected and atomic.
         const targetBytes = Math.max(0, Math.min(this.maxBytes - additionalBytes, Math.floor(this.maxBytes * 0.75)));
@@ -1222,7 +1232,7 @@ export class ArtifactStore {
         if (physicalWrites.length !== admission.projectedEntries) {
             throw new ServiceError('ARTIFACT_STORAGE_LIMIT', 'Artifact batch entry projection did not match prepared output');
         }
-        return this.withAtomicWrites(workspace, physicalWrites, (stored) => commit(logicalIndexes.map((index) => stored[index])), signal);
+        return this.withAtomicWrites(workspace, physicalWrites, (stored) => commit(logicalIndexes.map((index) => stored[index]), stored), signal);
     }
     plannedArtifactLink(workspace, write, bytes, sha256) {
         const manifestWithoutHash = {
@@ -1458,6 +1468,78 @@ export class ArtifactStore {
         await refreshArtifactManifest(manifestPath);
         return { bytes, mimeType: manifest.mimeType, name, totalSize };
     }
+    /** Read either one stored object or an authenticated chunk index as exact logical bytes. */
+    async readLogical(workspace, uri, options, signal) {
+        const initial = await this.read(workspace, uri, undefined, signal);
+        if (initial.mimeType !== options.mimeType)
+            throw new ServiceError('ARTIFACT_LOGICAL_TYPE_MISMATCH', `Logical artifact must use ${options.mimeType}`);
+        let parsed;
+        try {
+            parsed = JSON.parse(initial.bytes.toString('utf8'));
+        }
+        catch {
+            if (initial.totalSize > options.maxBytes)
+                throw new ServiceError('ARTIFACT_LOGICAL_LIMIT', 'Logical artifact exceeds its fixed byte ceiling');
+            return initial;
+        }
+        if (parsed === null ||
+            typeof parsed !== 'object' ||
+            Array.isArray(parsed) ||
+            parsed.type !== 'hoi4-agent.chunked-artifact') {
+            if (initial.totalSize > options.maxBytes)
+                throw new ServiceError('ARTIFACT_LOGICAL_LIMIT', 'Logical artifact exceeds its fixed byte ceiling');
+            return initial;
+        }
+        const index = parsed;
+        if (index.schemaVersion !== 1 ||
+            index.original === undefined ||
+            !Array.isArray(index.chunks) ||
+            index.chunks.length < 1 ||
+            index.chunks.length > options.maxChunks ||
+            index.original.mimeType !== options.mimeType ||
+            !Number.isSafeInteger(index.original.size) ||
+            index.original.size < 0 ||
+            index.original.size > options.maxBytes ||
+            !/^[a-f0-9]{64}$/u.test(index.original.sha256))
+            throw new ServiceError('ARTIFACT_LOGICAL_INVALID', 'Chunked logical artifact index is malformed or exceeds its fixed limits');
+        const buffers = [];
+        const chunkUris = new Set();
+        let offset = 0;
+        for (const [chunkIndex, candidate] of index.chunks.entries()) {
+            signal?.throwIfAborted();
+            if (candidate.index !== chunkIndex ||
+                candidate.offset !== offset ||
+                !Number.isSafeInteger(candidate.length) ||
+                candidate.length <= 0 ||
+                candidate.size !== candidate.length ||
+                candidate.mimeType !== 'application/octet-stream' ||
+                typeof candidate.uri !== 'string' ||
+                chunkUris.has(candidate.uri) ||
+                !/^[a-f0-9]{64}$/u.test(candidate.sha256) ||
+                offset + candidate.length > index.original.size)
+                throw new ServiceError('ARTIFACT_LOGICAL_INVALID', 'Chunked logical artifact entry is malformed');
+            chunkUris.add(candidate.uri);
+            const chunk = await this.read(workspace, candidate.uri, undefined, signal);
+            if (chunk.mimeType !== 'application/octet-stream' ||
+                chunk.totalSize !== candidate.length ||
+                chunk.bytes.length !== candidate.length ||
+                sha256Bytes(chunk.bytes) !== candidate.sha256)
+                throw new ServiceError('ARTIFACT_LOGICAL_INVALID', 'Chunked logical artifact content does not match its authenticated index');
+            buffers.push(chunk.bytes);
+            offset += chunk.bytes.length;
+        }
+        const bytes = Buffer.concat(buffers, index.original.size);
+        if (offset !== index.original.size ||
+            bytes.length !== index.original.size ||
+            sha256Bytes(bytes) !== index.original.sha256)
+            throw new ServiceError('ARTIFACT_LOGICAL_INVALID', 'Chunked logical artifact does not reconstruct its declared content');
+        return {
+            bytes,
+            mimeType: index.original.mimeType,
+            name: index.original.name,
+            totalSize: index.original.size,
+        };
+    }
     uri(workspaceId, sha256, provenanceHash, name) {
         return `hoi4-agent://workspace/${encodeURIComponent(workspaceId)}/artifact/${sha256}/${provenanceHash}/${encodeURIComponent(name)}`;
     }

package/dist/hoi4_agent_tools/core/condition-evaluator.js

@@ -344,6 +344,20 @@ function evaluateAssignmentCore(assignment, scenario, candidate, definitions, he
             state: compare(leftNumber, rightNumber, assignment.operator.text) ? 'true' : 'false',
             unresolved: [],
         };
+    if (/^(?:ROOT|THIS|PREV|FROM)$/iu.test(right)) {
+        const comparisonScope = resolveScopeContext(scenario, right, scopeContext);
+        if (comparisonScope === undefined ||
+            (comparisonScope.expression === 'ROOT' && scenario.actor === undefined))
+            return unresolved(assignment, candidate, `Scenario does not bind scope ${right}`);
+        if (typeof declared !== 'string')
+            return unresolved(assignment, candidate, `Trigger ${key} cannot compare its declared value with scope ${right}`);
+        return {
+            state: compare(declared, scopeIdentity(comparisonScope), assignment.operator.text)
+                ? 'true'
+                : 'false',
+            unresolved: [],
+        };
+    }
     if (typeof declared === 'string')
         return {
             state: compare(declared, right, assignment.operator.text) ? 'true' : 'false',
@@ -397,3 +411,5 @@ export function evaluateTriggerBlock(block, scenario, candidate, definitions, he
         trace: children.flatMap(({ trace }) => trace ?? []),
     };
 }
+/** Resolve a declared numeric expression with the same constants and scope rules as triggers. */
+export { numberValue as resolveConditionNumber };