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
023/**
024 * Invocation-scoped information for creating a durable MCP task.
025 *
026 * <p>This feature is available only for a task-augmentable operation whose
027 * request declared the MCP Tasks extension. Applications may use the admitted
028 * request to derive their own authorization binding and must persist
029 * {@link #getTaskOrigin()} in the same transaction or outbox operation as the
030 * durable work description. Neither this task creation context, the request context, nor any
031 * request cancelation token is durable work and none may be retained by a
032 * worker.
033 *
034 * <p>The task creation context does not schedule work, allocate a task ID, or imply that a
035 * client requested asynchronous execution. The server remains the sole
036 * per-invocation decision maker.
037 *
038 * @author <a href="https://www.revetkn.com">Mark Allen</a>
039 */
040@ThreadSafe
041public interface McpTaskCreationContext {
042        /**
043         * Returns the admitted request that is being considered for task creation.
044         *
045         * <p>Use this context synchronously to derive an application-owned task
046         * authorization binding. Do not retain it as the durable execution context.
047         *
048         * @return admitted task-augmentable request
049         */
050        @NonNull
051        McpRequestContext getRequestContext();
052
053        /**
054         * Returns the framework-derived origin to persist with the durable task.
055         *
056         * <p>When called by an interceptor for a typed tool, first access completes
057         * typed argument validation. Invalid arguments fail before an origin can be
058         * used or a tool handler can be entered.
059         *
060         * @return immutable non-wire task origin
061         * @throws IllegalArgumentException if the typed tool arguments are invalid or
062         *                                  the origin exceeds its durable bound
063         */
064        @NonNull
065        McpTaskOrigin getTaskOrigin();
066}