Class McpTaskOrigin

java.lang.Object
com.soklet.McpTaskOrigin
@ThreadSafe public final class McpTaskOrigin extends Object
Immutable, non-wire origin of one MCP task-augmented operation.

Soklet makes an invocation-scoped McpTaskCreationContext available before invoking a task-capable handler and derives this value only if application code requests it or the invocation produces a task handle. The persisted state is versioned framework data that lets a later request, potentially handled by another process or deployment generation, recover the original endpoint, operation, validated arguments, and output contract. It is intentionally opaque so later Tasks revisions can add origin data without widening this Java API.

An application that returns a task handle must store this complete value atomically with its durable work description. Its configured McpTaskManager must return a semantically equal origin with every snapshot of that task. Persist the exact text returned by toPersistedString() byte-for-byte in an opaque text or binary field and restore it with fromPersistedString(String). Do not route it through a database JSON type or another parse-and-render cycle that may normalize or discard representation details. The parser accepts insignificant whitespace, member reordering, and equivalent decimal scales, but exact storage is the forward-compatible durability boundary. Soklet compares the origin before returning the task handle and uses it to apply the original tool's output protections when the task completes.

Origin state may contain tool arguments or other sensitive application data. Store it with the same confidentiality and integrity protections as the task itself, do not log it, and do not expose it to clients. It is not an authorization decision or task-ownership binding; the task manager must independently bind and authorize each task using the admitted request.

Author:
Mark Allen

  • Method Details

    • fromPersistedState

      public static @NonNull McpTaskOrigin fromPersistedState(@NonNull McpJsonObject persistedState)
      Reconstructs an origin from framework state previously supplied by Soklet.

      Applications must preserve every member and value. Soklet canonicalizes object-member order and decimal scale for durable equality, then validates the supported version and semantics when the origin is used; construction establishes an immutable copy boundary.

      Parameters:
      persistedState - complete persisted origin state
      Returns:
      immutable task origin
      Throws:
      NullPointerException - if persistedState is null
      IllegalArgumentException - if the value cannot be represented by the bounded canonical origin codec

    • fromPersistedString

      public static @NonNull McpTaskOrigin fromPersistedString(@NonNull String persistedString)
      Reconstructs an origin from its bounded durable JSON representation.

      Store the exact representation as an opaque, non-normalizing text or binary value. Parsing accepts equivalent JSON object representations, including insignificant whitespace, member reordering, and numerically equivalent decimal scales, but toPersistedString() always returns Soklet's canonical form.

      Parameters:
      persistedString - persisted origin JSON
      Returns:
      immutable task origin
      Throws:
      NullPointerException - if persistedString is null
      IllegalArgumentException - if the value is not a bounded JSON object

    • getPersistedState

      public @NonNull McpJsonObject getPersistedState()
      Returns the complete opaque state that must be durably preserved.

      The returned object may contain sensitive operation arguments. It is not MCP response metadata and must never be sent to a client.

      Returns:
      immutable persisted origin state

    • toPersistedString

      public @NonNull String toPersistedString()
      Returns the bounded canonical JSON form for durable storage.

      The returned text may contain sensitive operation arguments. Store its exact UTF-8 representation in a non-normalizing text or binary field with the same confidentiality and integrity protections as the task. Do not parse and re-emit it, log it, or expose it to clients.

      Returns:
      canonical persisted origin JSON

    • equals

      public boolean equals(@Nullable Object other)
      Overrides:
      equals in class Object
      Returns:
      whether the other origin contains semantically equal JSON state

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object
      Returns:
      semantic persisted-state hash code

    • toString

      public @NonNull String toString()
      Overrides:
      toString in class Object
      Returns:
      a diagnostic rendering that does not expose origin state