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 * Programmatic handler for a tool that always completes with a structured
025 * Java result.
026 *
027 * <p>Soklet derives the output schema and intrinsic conversion plan from the
028 * result type declared by {@link McpToolRegistration.ArgumentTypeStage#argumentAndOutputTypes(
029 * Class, Class)}. A bare {@link String} result type is rejected; return prose
030 * through an advanced {@link McpToolHandler} and
031 * {@link McpCompleteResult#fromToolText(String)} instead.
032 *
033 * <p>For an operation that creates a durable task while retaining its eventual
034 * typed output contract, use
035 * {@link McpToolRegistration.CompleteHandlerStage#operationHandler(
036 * McpToolHandler)}.
037 * For an inline operation that needs explicit content or an {@code isError}
038 * result while retaining the typed output contract, use
039 * {@link McpToolRegistration.CompleteHandlerStage#inlineOperationHandler(
040 * McpToolHandler)}.
041 *
042 * <p>Implementations must be safe for concurrent invocation.
043 *
044 * @param <A> bound argument type
045 * @param <R> structured result type
046 * @author <a href="https://www.revetkn.com">Mark Allen</a>
047 */
048@ThreadSafe
049@FunctionalInterface
050public interface McpCompleteToolHandler<A, R> {
051        /**
052         * Handles one tool invocation.
053         *
054         * @param requestContext request metadata
055         * @param toolArguments converted and raw tool arguments
056         * @param invocationFeatures invocation-scoped optional features
057         * @return non-null structured result
058         * @throws Exception if application handling fails
059         */
060        @NonNull
061        R handle(@NonNull McpRequestContext requestContext,
062                        @NonNull McpToolArguments<@NonNull A> toolArguments,
063                        @NonNull McpInvocationFeatures invocationFeatures) throws Exception;
064}