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}