001/*
002 * Copyright 2022-2026 Revetware LLC.
003 * Licensed under the Apache License, Version 2.0 (the "License");
004 * you may not use this file except in compliance with the License.
005 * You may obtain a copy at https://www.apache.org/licenses/LICENSE-2.0
006 * Unless required by applicable law or agreed to in writing, software
007 * distributed under the License is distributed on an "AS IS" BASIS,
008 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
009 * See the License for the specific language governing permissions and
010 * limitations under the License.
011 */
012package com.soklet;
013
014import org.jspecify.annotations.NonNull;
015
016import javax.annotation.concurrent.ThreadSafe;
017
018/**
019 * Concurrently callable application-owned {@code skills/list} page handler.
020 *
021 * <p>On the first page, return an ordered subsequence of the initial selection
022 * supplied by the context. On continuation, restore the original ordered
023 * selection and page position from an authenticated application-owned cursor.
024 * Every returned registration must be an exact currently configured instance;
025 * duplicate URIs and foreign or reconstructed instances are rejected. Current
026 * access and discovery are rechecked on continuation without selecting a new
027 * variant. A complete skill manifest is never split between pages.
028 *
029 * <p>The application owns cursor integrity, endpoint/caller binding, expiry,
030 * content identities, retained snapshot availability, cross-page duplicate
031 * prevention, and cross-node portability. Current membership alone does not
032 * prove an old snapshot's content is unchanged. Do not retain request objects,
033 * invocation features, or localization contexts as snapshot state. Invalid or
034 * unavailable continuations should fail neutrally, without substituting content.
035 * The handler controls list pages, not canonical file reads.
036 *
037 * @author <a href="https://www.revetkn.com">Mark Allen</a>
038 */
039@ThreadSafe
040@FunctionalInterface
041public interface McpSkillListHandler {
042        /**
043         * Produces one complete page containing at most 32 registered skills.
044         *
045         * @param requestContext admitted request context
046         * @param skillListContext opaque cursor and authoritative first-page phase marker
047         * @param invocationFeatures invocation-scoped optional features
048         * @return non-null Skills page
049         * @throws Exception if page production or snapshot restoration fails
050         */
051        @NonNull
052        McpSkillPage handle(@NonNull McpRequestContext requestContext,
053                        @NonNull McpSkillListContext skillListContext,
054                        @NonNull McpInvocationFeatures invocationFeatures) throws Exception;
055}