001/*
002 * Copyright 2022-2026 Revetware LLC.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package com.soklet;
018
019import org.jspecify.annotations.NonNull;
020
021import javax.annotation.concurrent.ThreadSafe;
022
023import static java.util.Objects.requireNonNull;
024
025/**
026 * Immutable input to a task input-response update.
027 *
028 * <p>The request has already passed Soklet's structural validation and
029 * admission pipeline. A task manager must authorize and apply the update as
030 * one application-owned operation. It must ignore unknown, already-consumed,
031 * or no-longer-outstanding response keys, ignore a response whose MCP union
032 * variant does not match the outstanding request, and make accepted responses
033 * idempotent according to the MCP Tasks contract. Implementations may perform
034 * that correlation through
035 * {@link McpInputRequest#matchesInputResponse(McpJsonValue)}.
036 *
037 * <p>Instances intentionally retain reference identity. The nested request
038 * context represents one independently admitted invocation and may carry
039 * application principal and context objects; structurally equal-looking
040 * carriers must not be treated as the same authorization decision.
041 *
042 * @author <a href="https://www.revetkn.com">Mark Allen</a>
043 */
044@ThreadSafe
045public final class McpTaskUpdateContext {
046        @NonNull
047        private final McpRequestContext requestContext;
048        @NonNull
049        private final String taskId;
050        @NonNull
051        private final McpInputResponses inputResponses;
052
053        /**
054         * Creates a task-update context from its components.
055         *
056         * <p>This factory is useful for exercising application-provided task managers
057         * in isolation; Soklet constructs the authoritative contexts used for live
058         * requests.
059         *
060         * @param requestContext request context to supply to the task manager
061         * @param taskId nonblank task identifier without carriage-return or newline
062         *               characters
063         * @param inputResponses immutable client responses supplied by the update
064         * @return immutable task-update context
065         * @throws NullPointerException if an argument is null
066         * @throws IllegalArgumentException if the task ID is blank or contains a
067         * carriage-return or newline character
068         */
069        @NonNull
070        public static McpTaskUpdateContext fromComponents(
071                        @NonNull McpRequestContext requestContext,
072                        @NonNull String taskId,
073                        @NonNull McpInputResponses inputResponses) {
074                return new McpTaskUpdateContext(requestContext, taskId, inputResponses);
075        }
076
077        McpTaskUpdateContext(@NonNull McpRequestContext requestContext,
078                        @NonNull String taskId,
079                        @NonNull McpInputResponses inputResponses) {
080                this.requestContext = requireNonNull(requestContext);
081                this.taskId = McpTask.requireTaskId(taskId);
082                this.inputResponses = requireNonNull(inputResponses);
083        }
084
085        /** @return independently admitted current request */
086        @NonNull
087        public McpRequestContext getRequestContext() {
088                return this.requestContext;
089        }
090
091        /** @return durable task identifier */
092        @NonNull
093        public String getTaskId() {
094                return this.taskId;
095        }
096
097        /** @return immutable client responses supplied by this update */
098        @NonNull
099        public McpInputResponses getInputResponses() {
100                return this.inputResponses;
101        }
102}