hoi4-agent-tools 3.0.9 → 3.2.0

package/dist/hoi4_agent_tools/mcp/server/job-task-store.js

@@ -0,0 +1,67 @@
+import { CallToolResultSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { jobTaskTiming } from '../../core/job-store.js';
+import { OperationTaskService, operationTaskCallSchema, operationTaskId, operationTaskMessage, operationTaskStatus, } from '../../core/operation-tasks.js';
+import { ServiceError } from '../../core/result.js';
+import { currentTaskRequestSignal } from './task-request-context.js';
+function legacyTask(record) {
+    if (record.request.protocolTask === undefined)
+        throw new ServiceError('TASK_NOT_FOUND', 'The requested protocol task does not exist');
+    const message = operationTaskMessage(record);
+    const timing = jobTaskTiming(record);
+    return {
+        taskId: operationTaskId(record),
+        status: operationTaskStatus(record),
+        createdAt: record.createdAt,
+        lastUpdatedAt: timing.lastUpdatedAt,
+        ttl: timing.ttl,
+        pollInterval: record.request.protocolTask.pollInterval,
+        ...(message === undefined ? {} : { statusMessage: message }),
+    };
+}
+/** 2025 MCP task wire projection; execution and authorization live in the shared core. */
+export class PersistentJobTaskStore {
+    context;
+    tasks;
+    constructor(engine, context) {
+        this.context = context;
+        this.tasks = new OperationTaskService(engine);
+    }
+    async createTask(taskParams, requestId, request, sessionId) {
+        if (request.method !== 'tools/call')
+            throw new ServiceError('TASK_METHOD_UNSUPPORTED', 'Only tool calls support background tasks');
+        const call = operationTaskCallSchema.parse({
+            name: request.params?.name,
+            arguments: request.params?.arguments,
+        });
+        const signal = currentTaskRequestSignal();
+        return legacyTask(await this.tasks.submit(call, this.context(), {
+            background: request.params?.task !== undefined,
+            requestId,
+            ...(sessionId === undefined ? {} : { sessionId }),
+            ...(taskParams.ttl === undefined ? {} : { ttlMs: taskParams.ttl }),
+            ...(signal === undefined ? {} : { signal }),
+        }));
+    }
+    async getTask(value, _sessionId) {
+        const record = await this.tasks.get(value, this.context());
+        return record === null ? null : legacyTask(record);
+    }
+    async storeTaskResult(value, status, result, _sessionId) {
+        await this.tasks.assertPublishedResult(value, status, result, this.context());
+    }
+    async getTaskResult(value, _sessionId) {
+        return CallToolResultSchema.parse(await this.tasks.result(value, this.context()));
+    }
+    async updateTaskStatus(value, status, _statusMessage, _sessionId) {
+        if (status !== 'cancelled')
+            throw new ServiceError('TASK_STATUS_IMMUTABLE', 'Protocol task state is controlled by the authenticated job executor');
+        await this.tasks.cancel(value, this.context());
+    }
+    async listTasks(cursor, _sessionId) {
+        const page = await this.tasks.list(this.context(), cursor);
+        return {
+            tasks: page.records.map(legacyTask),
+            ...(page.nextCursor === undefined ? {} : { nextCursor: page.nextCursor }),
+        };
+    }
+}

package/dist/hoi4_agent_tools/mcp/server/legacy-task-tools.js

@@ -0,0 +1,20 @@
+import { CallToolResultSchema, CreateTaskResultSchema, GetTaskResultSchema, } from '@modelcontextprotocol/sdk/types.js';
+/** SDK-v1-only registration boundary for the 2025 task protocol. */
+export function registerLegacyTaskTools(server, definitions) {
+    for (const { name, ...configuration } of definitions) {
+        const handler = {
+            createTask: async (input, extra) => {
+                configuration.inputSchema.parse(input);
+                return CreateTaskResultSchema.parse({
+                    task: await extra.taskStore.createTask({
+                        ttl: extra.taskRequestedTtl ?? null,
+                        pollInterval: 250,
+                    }),
+                });
+            },
+            getTask: async (_input, extra) => GetTaskResultSchema.parse(await extra.taskStore.getTask(extra.taskId)),
+            getTaskResult: async (_input, extra) => CallToolResultSchema.parse(await extra.taskStore.getTaskResult(extra.taskId)),
+        };
+        server.experimental.tasks.registerToolTask(name, { ...configuration, execution: { taskSupport: 'optional' } }, handler);
+    }
+}

package/dist/hoi4_agent_tools/mcp/server/modern-tasks.js

@@ -0,0 +1,168 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { CallToolResultSchema } from '@modelcontextprotocol/core';
+import { ProtocolError, ProtocolErrorCode } from '@modelcontextprotocol/server';
+import { z } from 'zod/v4';
+import { jobTaskTiming } from '../../core/job-store.js';
+import { isMutationTask, operationTaskCallSchema, operationTaskId, operationTaskMessage, operationTaskStatus, } from '../../core/operation-tasks.js';
+import { ServiceError } from '../../core/result.js';
+import { taskToolCatalog } from './task-tool-catalog.js';
+/** Stable 2026-07-28 Tasks extension, not the deprecated SDK TaskSchema. */
+export const TASKS_EXTENSION = 'io.modelcontextprotocol/tasks';
+const capabilitySchema = z
+    .object({
+    extensions: z.object({ [TASKS_EXTENSION]: z.object({}).loose() }).loose(),
+})
+    .loose();
+const taskReferenceSchema = z.object({ taskId: z.string().min(1).max(256) }).strict();
+const taskUpdateSchema = taskReferenceSchema
+    .extend({
+    inputResponses: z
+        .record(z.string().max(1024), z.record(z.string(), z.json()))
+        .refine((value) => Object.keys(value).length <= 1024, 'Too many input responses'),
+})
+    .strict();
+const taskFields = {
+    taskId: z.string().min(1).max(256),
+    status: z.enum(['working', 'input_required', 'completed', 'failed', 'cancelled']),
+    statusMessage: z.string().max(8192).optional(),
+    createdAt: z.iso.datetime(),
+    lastUpdatedAt: z.iso.datetime(),
+    ttlMs: z.number().int().nonnegative().nullable(),
+    pollIntervalMs: z.number().int().nonnegative().optional(),
+};
+export const modernCreateTaskResultSchema = z
+    .object({
+    ...taskFields,
+    resultType: z.literal('task'),
+})
+    .strict();
+export const modernGetTaskResultSchema = z.discriminatedUnion('status', [
+    z
+        .object({ ...taskFields, resultType: z.literal('complete'), status: z.literal('working') })
+        .strict(),
+    z
+        .object({
+        ...taskFields,
+        resultType: z.literal('complete'),
+        status: z.literal('completed'),
+        result: z.record(z.string(), z.json()),
+    })
+        .strict(),
+    z
+        .object({ ...taskFields, resultType: z.literal('complete'), status: z.literal('cancelled') })
+        .strict(),
+]);
+export function hasModernTaskCapability(capabilities) {
+    return capabilitySchema.safeParse(capabilities).success;
+}
+function requireCapability(capabilities) {
+    if (!hasModernTaskCapability(capabilities))
+        throw new ProtocolError(ProtocolErrorCode.MissingRequiredClientCapability, 'Missing required client capability', {
+            requiredCapabilities: { extensions: { [TASKS_EXTENSION]: {} } },
+        });
+}
+function taskFieldsFor(record, taskId) {
+    if (record.request.protocolTask === undefined)
+        throw new ProtocolError(ProtocolErrorCode.InvalidParams, 'Task not found');
+    const message = operationTaskMessage(record);
+    const timing = jobTaskTiming(record);
+    return {
+        taskId,
+        // Stored job failures are ordinary tool errors, not JSON-RPC failures.
+        status: record.status === 'failed' ? 'completed' : operationTaskStatus(record),
+        createdAt: record.createdAt,
+        lastUpdatedAt: timing.lastUpdatedAt,
+        ttlMs: timing.ttl,
+        pollIntervalMs: record.request.protocolTask.pollInterval,
+        ...(message === undefined ? {} : { statusMessage: message }),
+    };
+}
+/** Projects the same authenticated job result onto the modern result vocabulary. */
+function modernToolResult(record, result) {
+    const parsed = CallToolResultSchema.parse(result);
+    const definition = taskToolCatalog.find(({ name }) => name === record.request.toolName);
+    if (definition === undefined)
+        throw new ServiceError('TASK_TOOL_UNSUPPORTED', 'The task tool is not registered');
+    if (!parsed.isError || parsed.structuredContent !== undefined)
+        definition.outputSchema.parse(parsed.structuredContent);
+    return { ...parsed, resultType: 'complete', ttlMs: 0, cacheScope: 'private' };
+}
+/** Per-request negotiated wire adapter. It never accepts ownership or grants from client metadata. */
+export class ModernTaskAdapter {
+    tasks;
+    constructor(tasks) {
+        this.tasks = tasks;
+    }
+    async call(input, capabilities, context, options) {
+        const parsed = operationTaskCallSchema.safeParse(input);
+        if (!parsed.success)
+            throw new ProtocolError(ProtocolErrorCode.InvalidParams, 'Invalid tool call');
+        // Capability advertisement is not a request to background a rewrite without a retry key.
+        const background = hasModernTaskCapability(capabilities) &&
+            (!isMutationTask(parsed.data.name) || typeof parsed.data.arguments.requestKey === 'string');
+        const record = await this.tasks.submit(parsed.data, context, { ...options, background });
+        const taskId = this.tasks.authenticatedTaskId(record);
+        if (background)
+            return modernCreateTaskResultSchema.parse({
+                resultType: 'task',
+                ...taskFieldsFor(record, taskId),
+            });
+        let latest = record;
+        while (operationTaskStatus(latest) === 'working') {
+            options.signal?.throwIfAborted();
+            await delay(100, undefined, { signal: options.signal });
+            latest = await this.known(taskId, context);
+        }
+        return modernToolResult(latest, await this.tasks.result(operationTaskId(record), context));
+    }
+    async handle(method, params, capabilities, context, signal) {
+        if (!['tasks/get', 'tasks/update', 'tasks/cancel'].includes(method))
+            throw new ProtocolError(ProtocolErrorCode.MethodNotFound, 'Method not found');
+        requireCapability(capabilities);
+        signal?.throwIfAborted();
+        const parsed = (method === 'tasks/update' ? taskUpdateSchema : taskReferenceSchema).safeParse(params);
+        if (!parsed.success)
+            throw new ProtocolError(ProtocolErrorCode.InvalidParams, 'Invalid task parameters');
+        try {
+            const record = await this.known(parsed.data.taskId, context, method === 'tasks/get');
+            signal?.throwIfAborted();
+            if (method === 'tasks/cancel') {
+                await this.tasks.cancel(operationTaskId(record), context);
+                return { resultType: 'complete' };
+            }
+            // These offline operations never solicit input during execution. Unknown/satisfied keys
+            // are acknowledged without changing state, as required by the extension.
+            if (method === 'tasks/update')
+                return { resultType: 'complete' };
+            const fields = taskFieldsFor(record, parsed.data.taskId);
+            return modernGetTaskResultSchema.parse({
+                ...fields,
+                resultType: 'complete',
+                ...(fields.status !== 'completed'
+                    ? {}
+                    : {
+                        result: modernToolResult(record, await this.tasks.result(operationTaskId(record), context)),
+                    }),
+            });
+        }
+        catch (error) {
+            if (error instanceof ProtocolError)
+                throw error;
+            if (error instanceof ServiceError && error.code === 'TASK_NOT_FOUND')
+                throw new ProtocolError(ProtocolErrorCode.InvalidParams, 'Task not found');
+            if (error instanceof ServiceError && error.code === 'AUTH_SCOPE_REQUIRED')
+                throw new ProtocolError(-32000, 'The operation requires write authorization', {
+                    code: error.code,
+                });
+            if (signal?.aborted)
+                throw error;
+            throw new ProtocolError(ProtocolErrorCode.InternalError, 'The task operation could not be completed');
+        }
+    }
+    async known(value, context, resume = true) {
+        const record = await this.tasks.getAuthenticatedTask(value, context, { resume });
+        if (record === null)
+            throw new ProtocolError(ProtocolErrorCode.InvalidParams, 'Task not found');
+        return record;
+    }
+}

package/dist/hoi4_agent_tools/mcp/server/progress.js

@@ -6,35 +6,39 @@ export const PROGRESS_HEARTBEAT_INTERVAL_MS = 10_000;
 const reporters = new WeakMap();
 const heartbeatOwners = new WeakSet();
 export function progressReporter(extra) {
-    const existing = reporters.get(extra);
+    return reporterFor(extra, extra.signal, extra._meta?.progressToken, (notification) => extra.sendNotification(notification));
+}
+/** Use the SDK's request-related notification route, including HTTP response-stream association. */
+export function modernProgressReporter(context) {
+    const request = context.mcpReq;
+    return reporterFor(request, request.signal, request._meta?.progressToken, (notification) => request.notify(notification));
+}
+function reporterFor(owner, signal, progressToken, notify) {
+    const existing = reporters.get(owner);
     if (existing !== undefined)
         return existing;
     let latest = Number.NEGATIVE_INFINITY;
     let latestTotal = 1;
     let latestMessage = 'Waiting for server execution capacity';
     const reporter = {
-        signal: extra.signal,
+        signal,
         async report(progress, total, message) {
-            extra.signal.throwIfAborted();
+            signal.throwIfAborted();
             latestTotal = total;
             latestMessage = message;
             const normalized = Math.max(latest, Math.min(progress, total));
-            const progressToken = extra._meta?.progressToken;
             if (progressToken === undefined)
                 return;
             if (normalized <= latest)
                 return;
             latest = normalized;
-            await extra
-                .sendNotification({
+            await notify({
                 method: 'notifications/progress',
                 params: { progressToken, progress: normalized, total, message },
-            })
-                .catch(() => undefined);
+            }).catch(() => undefined);
         },
         async pulse(message = latestMessage) {
-            extra.signal.throwIfAborted();
-            const progressToken = extra._meta?.progressToken;
+            signal.throwIfAborted();
             if (progressToken === undefined)
                 return;
             // Use the next representably larger value rather than repeating a value, which
@@ -42,8 +46,7 @@ export function progressReporter(extra) {
             latest = Number.isFinite(latest)
                 ? latest + Math.max(1, Math.abs(latest)) * Number.EPSILON * 2
                 : 0;
-            await extra
-                .sendNotification({
+            await notify({
                 method: 'notifications/progress',
                 params: {
                     progressToken,
@@ -51,11 +54,10 @@ export function progressReporter(extra) {
                     ...(latest <= latestTotal ? { total: latestTotal } : {}),
                     message,
                 },
-            })
-                .catch(() => undefined);
+            }).catch(() => undefined);
         },
     };
-    reporters.set(extra, reporter);
+    reporters.set(owner, reporter);
     return reporter;
 }
 /**

package/dist/hoi4_agent_tools/mcp/server/request-lifecycle.js

@@ -1,4 +1,36 @@
+import { CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { progressReporter, withProgressHeartbeat } from './progress.js';
+import { withTaskRequestSignal } from './task-request-context.js';
+// Durable task compatibility and cancellation are control traffic. They must
+// remain responsive while every domain-execution slot is occupied.
+const controlTools = new Set(['hoi4.job_inspect', 'hoi4.job_cancel']);
+const backgroundTools = new Set([
+    'hoi4.impact_inspect',
+    'hoi4.decision_inspect',
+    'hoi4.event_inspect',
+    'hoi4.event_render',
+    'hoi4.event_compare',
+    'hoi4.tech_inspect',
+    'hoi4.tech_render',
+    'hoi4.tech_compare',
+    'hoi4.probability_inspect',
+    'hoi4.probability_evaluate',
+    'hoi4.probability_sweep',
+    'hoi4.probability_simulate',
+    'hoi4.probability_sequence',
+    'hoi4.probability_compare',
+    'hoi4.probability_render',
+    'hoi4.map_inspect',
+    'hoi4.map_render',
+    'hoi4.map_rewrite',
+    'hoi4.gui_inspect',
+    'hoi4.gui_render',
+    'hoi4.gui_rewrite',
+    'hoi4.focus_inspect',
+    'hoi4.focus_render',
+    'hoi4.focus_raster',
+    'hoi4.focus_rewrite',
+]);
 /** Wrap the public SDK handler registration so optional tools receive the same lifecycle. */
 export function installRequestLifecycle(server, engine) {
     const register = server.server.setRequestHandler.bind(server.server);
@@ -8,6 +40,19 @@ export function installRequestLifecycle(server, engine) {
             if (request.method !== 'tools/call')
                 return handler(request, extra);
             const progress = progressReporter(extra);
+            const taskCall = CallToolRequestSchema.safeParse(request);
+            if (taskCall.success && controlTools.has(taskCall.data.params.name))
+                return handler(request, extra);
+            if (taskCall.success && backgroundTools.has(taskCall.data.params.name)) {
+                return withProgressHeartbeat(async () => {
+                    const result = await withTaskRequestSignal(extra.signal, () => handler(request, extra));
+                    if (taskCall.data.params.task === undefined) {
+                        await progress.report(2, 3, 'Retrieving persistent operation result');
+                        await progress.report(3, 3, 'Persistent operation complete');
+                    }
+                    return result;
+                }, progress);
+            }
             return withProgressHeartbeat(() => engine.requests.run(owner, Buffer.byteLength(JSON.stringify(request)), extra.signal, () => engine.sharedRequests.run(extra.signal, async () => handler(request, extra))), progress);
         });
     };