Class McpInMemoryTaskManager

java.lang.Object

com.soklet.McpInMemoryTaskManager

All Implemented Interfaces:

McpTaskManager

@ThreadSafe
public final class McpInMemoryTaskManager
extends Object
implements McpTaskManager

Thread-safe, task-count-bounded, process-local manager for development and tests.

State exists only in this manager instance and is lost when its JVM exits. The manager provides no cross-process coordination, durable persistence, work queue, worker, lease, fencing, retry, or crash-recovery facility. It is therefore not a production task backend. Applications remain responsible for executing work and explicitly advancing task state through this class.

Retention is bounded by task count. Task values remain subject to Soklet's ordinary MCP request, JSON, and response limits when they cross the protocol boundary; this development helper does not attempt to estimate their JVM object sizes.

Worker mutations establish status-specific payload shape, not delivery validity under the origin tool's output schema and input declarations. Soklet performs those checks when reading or projecting a task. A failed delivery does not change authoritative state or notify the worker.

The manager never creates a thread and requires no close operation. Expired tasks are removed opportunistically during later manager operations. It never evicts an unexpired task to make room for another task.

Author:

Mark Allen

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	McpInMemoryTaskManager.Builder	Single-threaded builder for an in-memory task manager.

Method Summary

Modifier and Type	Method	Description
static @NonNull McpInMemoryTaskManager.Builder	builder()	Vends a builder initialized with finite development defaults.
@NonNull McpTask	cancelTask(@NonNull String taskId, @Nullable String taskStatusMessage)	Marks a retained nonterminal task as canceled.
@NonNull McpTask	completeTask(@NonNull String taskId, @NonNull McpCompleteResult completeResult, @Nullable String taskStatusMessage)	Completes a retained nonterminal task.
@NonNull McpTask	createTask(@NonNull McpTaskCreationContext taskCreationContext)	Creates a working task for the current task-capable tool invocation.
@NonNull McpTask	failTask(@NonNull String taskId, @NonNull McpJsonRpcError failure, @Nullable String taskStatusMessage)	Fails a retained nonterminal task with a client-visible JSON-RPC error.
@NonNull Optional<@NonNull McpTask>	findTask(@NonNull McpTaskRequestContext taskRequestContext)	Finds the task visible to the requesting MCP authorization partition and endpoint.
@NonNull Optional<@NonNull McpTask>	findTask(@NonNull String taskId)	Finds a task for trusted application or worker code.
@NonNull Integer	getMaximumRetainedTasks()
@NonNull Duration	getPollInterval()
@NonNull Optional<@NonNull McpTaskEventPublisher>	getTaskEventPublisher()	Returns this manager's process-local task-event publisher.
@NonNull Duration	getTaskTimeToLive()
@NonNull Boolean	isTaskCancelationRequested(@NonNull String taskId)	Returns whether a client has requested cancelation of a retained task.
@NonNull McpTask	markTaskWorking(@NonNull String taskId, @Nullable String taskStatusMessage)	Marks a retained nonterminal task as working.
void	requestTaskCancelation(@NonNull McpTaskRequestContext taskRequestContext)	Records a cooperative cancelation request for a nonterminal task visible to the requesting MCP authorization partition and endpoint.
@NonNull McpTask	requestTaskInput(@NonNull String taskId, @NonNull Map<@NonNull String, ? extends @NonNull McpInputRequest> inputRequests, @Nullable String taskStatusMessage)	Places a retained nonterminal task into the input-required state.
@NonNull McpInputResponses	takeTaskInputResponses(@NonNull String taskId)	Atomically takes and clears input responses accepted for a retained task.
void	updateTask(@NonNull McpTaskUpdateContext taskUpdateContext)	Accepts responses for currently outstanding input requests visible to the requesting MCP authorization partition and endpoint.

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

builder

public static @NonNull McpInMemoryTaskManager.Builder builder()

Vends a builder initialized with finite development defaults.

Returns:

in-memory task-manager builder

getMaximumRetainedTasks

public @NonNull Integer getMaximumRetainedTasks()

Returns:

positive maximum number of simultaneously retained tasks

getTaskTimeToLive

public @NonNull Duration getTaskTimeToLive()

Returns:

finite lifetime of every task, measured from its creation

getPollInterval

public @NonNull Duration getPollInterval()

Returns:

positive polling interval advertised for every task

getTaskEventPublisher

public @NonNull Optional<@NonNull McpTaskEventPublisher> getTaskEventPublisher()

Returns this manager's process-local task-event publisher.

Specified by:

getTaskEventPublisher in interface McpTaskManager

Returns:

task-event publisher

createTask

public @NonNull McpTask createTask(@NonNull McpTaskCreationContext taskCreationContext)

Creates a working task for the current task-capable tool invocation.

The task creation context supplies Soklet's immutable task origin and the current endpoint and authorization partition. The manager copies those values and never retains the task creation context, request context, principal, or application context. The returned task is immediately available through both trusted and appropriately authorized protocol lookup.

Parameters:

taskCreationContext - current task creation context

Returns:

newly created working task

Throws:

NullPointerException - if the task creation context or either of its required values is null

IllegalStateException - if the finite task capacity is exhausted

findTask

public @NonNull Optional<@NonNull McpTask> findTask(@NonNull String taskId)

Finds a task for trusted application or worker code.

This overload deliberately does not perform protocol authorization. Use of a task ID through an MCP request always goes through the context-taking SPI method, which does perform authorization.

Parameters:

taskId - task identifier

Returns:

immutable current task, if retained

markTaskWorking

public @NonNull McpTask markTaskWorking(@NonNull String taskId,
 @Nullable String taskStatusMessage)
                                 throws McpTaskNotFoundException

Marks a retained nonterminal task as working. Outstanding input requests are superseded; later responses for their keys are ignored.

Parameters:

taskId - task identifier

taskStatusMessage - optional client-visible status message

Returns:

immutable updated task

Throws:

McpTaskNotFoundException - if the task is absent or expired

IllegalStateException - if the task is terminal

requestTaskInput

public @NonNull McpTask requestTaskInput(@NonNull String taskId,
 @NonNull Map<@NonNull String, ? extends @NonNull McpInputRequest> inputRequests,
 @Nullable String taskStatusMessage)
                                  throws McpTaskNotFoundException

Places a retained nonterminal task into the input-required state.

New request keys must not have been used previously during the task's lifetime. Repeating an identical, still-outstanding key and request is an idempotent no-op; every other reuse is rejected. Accepted client responses must be taken before another input round begins.

This mutation does not validate requests against the originating tool's input declarations or a later caller's capabilities. An undeclared stored request fails the subsequent protocol read with a fixed internal error; a polling client lacking an outstanding request's capability receives the missing-capability protocol error. Both leave state unchanged. Trusted worker code may supersede outstanding requests through markTaskWorking(String, String) before a corrected round.

Parameters:

taskId - task identifier

inputRequests - nonempty input requests to add

taskStatusMessage - optional client-visible status message

Returns:

immutable updated task

Throws:

McpTaskNotFoundException - if the task is absent or expired

IllegalStateException - if the task is terminal or accepted input remains untaken

IllegalArgumentException - if the map is empty or reuses a key

completeTask

public @NonNull McpTask completeTask(@NonNull String taskId,
 @NonNull McpCompleteResult completeResult,
 @Nullable String taskStatusMessage)
                              throws McpTaskNotFoundException

Completes a retained nonterminal task. A tool result whose isError value is true is still a completed task result.

Completion does not prevalidate the originating tool's output schema, transport limits or a serving node's current sanitizer. Those checks occur during delivery. A failed read does not revert completion or synthesize a failed task, and terminal state cannot be overwritten through this manager. Applications must produce valid output before completing their work.

Parameters:

taskId - task identifier

completeResult - complete MCP result

taskStatusMessage - optional client-visible status message

Returns:

immutable completed task

Throws:

McpTaskNotFoundException - if the task is absent or expired

IllegalStateException - if the task is terminal

failTask

public @NonNull McpTask failTask(@NonNull String taskId,
 @NonNull McpJsonRpcError failure,
 @Nullable String taskStatusMessage)
                          throws McpTaskNotFoundException

Fails a retained nonterminal task with a client-visible JSON-RPC error.

Parameters:

taskId - task identifier

failure - task failure

taskStatusMessage - optional client-visible status message

Returns:

immutable failed task

Throws:

McpTaskNotFoundException - if the task is absent or expired

IllegalStateException - if the task is terminal

cancelTask

public @NonNull McpTask cancelTask(@NonNull String taskId,
 @Nullable String taskStatusMessage)
                            throws McpTaskNotFoundException

Marks a retained nonterminal task as canceled. This worker-facing state transition is separate from the protocol's cooperative cancelation request.

Parameters:

taskId - task identifier

taskStatusMessage - optional client-visible status message

Returns:

immutable canceled task

Throws:

McpTaskNotFoundException - if the task is absent or expired

IllegalStateException - if the task is terminal

takeTaskInputResponses

public @NonNull McpInputResponses takeTaskInputResponses(@NonNull String taskId)
                                                  throws McpTaskNotFoundException

Atomically takes and clears input responses accepted for a retained task. This trusted worker operation is nonblocking.

Parameters:

taskId - task identifier

Returns:

accepted responses, possibly empty

Throws:

McpTaskNotFoundException - if the task is absent or expired

isTaskCancelationRequested

public @NonNull Boolean isTaskCancelationRequested(@NonNull String taskId)
                                            throws McpTaskNotFoundException

Returns whether a client has requested cancelation of a retained task. The signal never changes task status by itself.

Parameters:

taskId - task identifier

Returns:

whether cancelation was requested

Throws:

McpTaskNotFoundException - if the task is absent or expired

findTask

public @NonNull Optional<@NonNull McpTask> findTask(@NonNull McpTaskRequestContext taskRequestContext)

Finds the task visible to the requesting MCP authorization partition and endpoint. An unknown task and a task owned by another partition or endpoint are deliberately indistinguishable.

Specified by:

findTask in interface McpTaskManager

Parameters:

taskRequestContext - protocol task lookup context

Returns:

immutable current task, if retained and authorized

updateTask

public void updateTask(@NonNull McpTaskUpdateContext taskUpdateContext)
                throws McpTaskNotFoundException

Accepts responses for currently outstanding input requests visible to the requesting MCP authorization partition and endpoint. Unknown or already consumed response keys and responses whose union variant does not match the outstanding request are ignored.

Specified by:

updateTask in interface McpTaskManager

Parameters:

taskUpdateContext - protocol task update context

Throws:

McpTaskNotFoundException - if the task is absent, expired, or not visible to this request

requestTaskCancelation

public void requestTaskCancelation(@NonNull McpTaskRequestContext taskRequestContext)
                            throws McpTaskNotFoundException

Records a cooperative cancelation request for a nonterminal task visible to the requesting MCP authorization partition and endpoint. This signal does not itself change the task's status.

Specified by:

requestTaskCancelation in interface McpTaskManager

Parameters:

taskRequestContext - protocol task cancelation context

Throws:

McpTaskNotFoundException - if the task is absent, expired, or not visible to this request