Interface McpTaskManager

All Known Implementing Classes:
McpInMemoryTaskManager
@ThreadSafe public interface McpTaskManager
Thread-safe application authority for MCP task state and client actions.

A production implementation normally delegates to application-owned durable storage and job infrastructure shared by every eligible Soklet node. It owns task-ID generation, persistence, retention, task-to-principal and tenant binding, legal atomic state transitions, client-input deduplication, cancelation intent, and publication of already-durable status changes. Soklet does not close the manager or start, stop, schedule, retry, lease, or fence application workers.

Every operation is independently admitted before this interface is called, but admission alone does not authorize a task. Implementations must atomically compare the current request's endpoint and admitted application identity with their durable task binding. Unknown and unauthorized task IDs must be indistinguishable: findTask(McpTaskRequestContext) returns an empty optional for either case, while mutation methods throw McpTaskNotFoundException for either case. Other failures are treated as internal errors and must not expose exception-derived data to the client.

A task must be durably readable through findTask(McpTaskRequestContext) before its handler returns McpTaskCreatedResult. Correct production behavior cannot depend on the original HTTP connection, sticky routing, or the originating process remaining alive. Implementations should assume at-least-once work execution and use leases, fencing, idempotency, and an outbox or equivalent recovery mechanism where their workload requires them.

Soklet validates returned snapshots at delivery time. Invalid stored output or undeclared input requests fail polling with a fixed internal error and suppress notification projection without mutating task state, publishing a state change, or notifying an application worker. Current access policy, sanitization, and transport limits can also prevent delivery without proving that the underlying work failed. Applications must validate their output and input requests before storing them; preserve the framework origin as opaque data rather than interpreting its persisted members. This interface supplies no worker-side validation callback.

Author:
Mark Allen

  • Method Details

    • fromInMemoryDefaults

      static @NonNull McpInMemoryTaskManager fromInMemoryDefaults()
      Creates Soklet's explicit process-local task manager with documented bounded defaults.

      The returned manager is intended for development, tests, simulation, and deliberately ephemeral single-process applications. Its state is lost on restart and is invisible to other nodes. It provides no worker, executor, queue, outbox, leases, fencing, failover, or crash recovery and is never selected implicitly by an McpServer.

      Returns:
      a new independent in-memory task manager

    • getTaskEventPublisher

      default @NonNull Optional<@NonNull McpTaskEventPublisher> getTaskEventPublisher()
      Returns the optional application-owned publisher for durable task-state changes.

      When present, Soklet subscribes while the server is running and may project matching events onto subscriptions/listen streams as notifications/tasks. The publisher carries task IDs only; Soklet performs a fresh, authorized lookup through this manager before sending a current snapshot. Polling through tasks/get remains authoritative.

      This is a stable manager property: every invocation for the manager's lifetime must return either an empty optional or an optional containing the same publisher instance. Each built McpServer snapshots the property once during construction; it does not observe a later publisher change. This lets production and simulator servers backed by the same manager attach independently to one shared event topology.

      The default returns an empty optional, enabling polling without task notifications. Soklet neither starts nor closes the publisher.

      Returns:
      task-event publisher, or the empty optional when task notifications are disabled

    • findTask

      @NonNull Optional<@NonNull McpTask> findTask(@NonNull McpTaskRequestContext taskRequestContext) throws Exception
      Finds the current authoritative task snapshot after atomically authorizing the request.

      Soklet may invoke this method asynchronously to project a task-change event. A subscription can disconnect while that lookup is in progress, so implementations should apply finite storage deadlines and respond promptly to thread interruption; a result may be discarded when the subscription is no longer active.

      After an authorized lookup, Soklet checks outstanding input requests against the polling request's current client capabilities. Missing support fails that poll with the missing-capability protocol error, without sending a partial snapshot or changing authoritative state. Working and terminal snapshots do not require capabilities for unused input declarations.

      Parameters:
      taskRequestContext - independently admitted lookup context
      Returns:
      current snapshot, or empty when the task is unknown or unauthorized
      Throws:
      Exception - if task storage or authorization fails unexpectedly

    • updateTask

      void updateTask(@NonNull McpTaskUpdateContext taskUpdateContext) throws Exception
      Atomically authorizes and accepts client responses to outstanding task input requests.

      A request may supply any partial subset of outstanding responses. Unknown, already-consumed, and superseded response keys are ignored, as is a response whose MCP union variant does not match its outstanding request. Implementations may perform that correlation through McpInputRequest.matchesInputResponse(McpJsonValue). The update acknowledgement may precede a worker's subsequent observable state change.

      Parameters:
      taskUpdateContext - independently admitted task update
      Throws:
      McpTaskNotFoundException - if the task is unknown or unauthorized
      Exception - if task storage, authorization, or update processing fails unexpectedly

    • requestTaskCancelation

      void requestTaskCancelation(@NonNull McpTaskRequestContext taskRequestContext) throws Exception
      Atomically authorizes and records a client's durable task-cancelation intent.

      A successful return acknowledges intent only. A worker may later honor it, or completion or failure may win the race. This method is unrelated to request-scoped CancelationToken and notifications/cancelled behavior. A known terminal task must be accepted idempotently; only an unknown or unauthorized task uses the not-found signal.

      Parameters:
      taskRequestContext - independently admitted task-cancelation request
      Throws:
      McpTaskNotFoundException - if the task is unknown or unauthorized
      Exception - if task storage, authorization, or intent recording fails unexpectedly