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 reporter for MCP progress notifications.
025 *
026 * <p>A reporter is available through
027 * {@link McpInvocationFeatures#getProgressReporter()} only when the initiating
028 * request supplied a valid progress token and Soklet can safely commit
029 * request-scoped progress to the response stream. Implementations are
030 * thread-safe. Reports from concurrent callers are serialized in accepted
031 * progress order.
032 *
033 * <p>Progress is supported for MCP 2025-06-18, 2025-11-25, and 2026-07-28.
034 * The first accepted update commits the originating POST response to SSE;
035 * a handler that reports no progress retains a nonstreaming JSON response.
036 * Progress does not divide the final tool, prompt, resource, or completion
037 * result into chunks: one whole terminal result or error follows the
038 * notifications.
039 *
040 * @author <a href="https://www.revetkn.com">Mark Allen</a>
041 */
042@ThreadSafe
043@FunctionalInterface
044public interface McpProgressReporter {
045        /**
046         * Reports increasing progress for the active invocation.
047         *
048         * <p>An update equal to the last accepted progress value is coalesced. A
049         * lower value is rejected while the invocation remains active. Once the
050         * invocation is canceled or terminal, or its response writer has detached,
051         * reports have no effect.
052         *
053         * <p>Reporting is synchronous and may block while the bounded
054         * request-scoped outbound queue applies backpressure. If that wait is
055         * interrupted, Soklet preserves the calling thread's interrupt status and
056         * does not accept the update.
057         *
058         * @param update immutable progress update
059         * @throws NullPointerException if {@code update} is null
060         * @throws IllegalArgumentException if progress decreases while the
061         * invocation is active
062         */
063        void report(@NonNull McpProgressUpdate update);
064}