update

node_modules/@modelcontextprotocol/sdk/dist/esm/experimental/tasks/interfaces.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Experimental task interfaces for MCP SDK.
+ * WARNING: These APIs are experimental and may change without notice.
+ */
+import { Task, RequestId, Result, JSONRPCRequest, JSONRPCNotification, JSONRPCResultResponse, JSONRPCErrorResponse, ServerRequest, ServerNotification, CallToolResult, GetTaskResult, ToolExecution, Request } from '../../types.js';
+import { CreateTaskResult } from './types.js';
+import type { RequestHandlerExtra, RequestTaskStore } from '../../shared/protocol.js';
+import type { ZodRawShapeCompat, AnySchema, ShapeOutput } from '../../server/zod-compat.js';
+/**
+ * Extended handler extra with task store for task creation.
+ * @experimental
+ */
+export interface CreateTaskRequestHandlerExtra extends RequestHandlerExtra<ServerRequest, ServerNotification> {
+    taskStore: RequestTaskStore;
+}
+/**
+ * Extended handler extra with task ID and store for task operations.
+ * @experimental
+ */
+export interface TaskRequestHandlerExtra extends RequestHandlerExtra<ServerRequest, ServerNotification> {
+    taskId: string;
+    taskStore: RequestTaskStore;
+}
+/**
+ * Base callback type for tool handlers.
+ * @experimental
+ */
+export type BaseToolCallback<SendResultT extends Result, ExtraT extends RequestHandlerExtra<ServerRequest, ServerNotification>, Args extends undefined | ZodRawShapeCompat | AnySchema = undefined> = Args extends ZodRawShapeCompat ? (args: ShapeOutput<Args>, extra: ExtraT) => SendResultT | Promise<SendResultT> : Args extends AnySchema ? (args: unknown, extra: ExtraT) => SendResultT | Promise<SendResultT> : (extra: ExtraT) => SendResultT | Promise<SendResultT>;
+/**
+ * Handler for creating a task.
+ * @experimental
+ */
+export type CreateTaskRequestHandler<SendResultT extends Result, Args extends undefined | ZodRawShapeCompat | AnySchema = undefined> = BaseToolCallback<SendResultT, CreateTaskRequestHandlerExtra, Args>;
+/**
+ * Handler for task operations (get, getResult).
+ * @experimental
+ */
+export type TaskRequestHandler<SendResultT extends Result, Args extends undefined | ZodRawShapeCompat | AnySchema = undefined> = BaseToolCallback<SendResultT, TaskRequestHandlerExtra, Args>;
+/**
+ * Interface for task-based tool handlers.
+ * @experimental
+ */
+export interface ToolTaskHandler<Args extends undefined | ZodRawShapeCompat | AnySchema = undefined> {
+    createTask: CreateTaskRequestHandler<CreateTaskResult, Args>;
+    getTask: TaskRequestHandler<GetTaskResult, Args>;
+    getTaskResult: TaskRequestHandler<CallToolResult, Args>;
+}
+/**
+ * Task-specific execution configuration.
+ * taskSupport cannot be 'forbidden' for task-based tools.
+ * @experimental
+ */
+export type TaskToolExecution<TaskSupport = ToolExecution['taskSupport']> = Omit<ToolExecution, 'taskSupport'> & {
+    taskSupport: TaskSupport extends 'forbidden' | undefined ? never : TaskSupport;
+};
+/**
+ * Represents a message queued for side-channel delivery via tasks/result.
+ *
+ * This is a serializable data structure that can be stored in external systems.
+ * All fields are JSON-serializable.
+ */
+export type QueuedMessage = QueuedRequest | QueuedNotification | QueuedResponse | QueuedError;
+export interface BaseQueuedMessage {
+    /** Type of message */
+    type: string;
+    /** When the message was queued (milliseconds since epoch) */
+    timestamp: number;
+}
+export interface QueuedRequest extends BaseQueuedMessage {
+    type: 'request';
+    /** The actual JSONRPC request */
+    message: JSONRPCRequest;
+}
+export interface QueuedNotification extends BaseQueuedMessage {
+    type: 'notification';
+    /** The actual JSONRPC notification */
+    message: JSONRPCNotification;
+}
+export interface QueuedResponse extends BaseQueuedMessage {
+    type: 'response';
+    /** The actual JSONRPC response */
+    message: JSONRPCResultResponse;
+}
+export interface QueuedError extends BaseQueuedMessage {
+    type: 'error';
+    /** The actual JSONRPC error */
+    message: JSONRPCErrorResponse;
+}
+/**
+ * Interface for managing per-task FIFO message queues.
+ *
+ * Similar to TaskStore, this allows pluggable queue implementations
+ * (in-memory, Redis, other distributed queues, etc.).
+ *
+ * Each method accepts taskId and optional sessionId parameters to enable
+ * a single queue instance to manage messages for multiple tasks, with
+ * isolation based on task ID and session ID.
+ *
+ * All methods are async to support external storage implementations.
+ * All data in QueuedMessage must be JSON-serializable.
+ *
+ * @experimental
+ */
+export interface TaskMessageQueue {
+    /**
+     * Adds a message to the end of the queue for a specific task.
+     * Atomically checks queue size and throws if maxSize would be exceeded.
+     * @param taskId The task identifier
+     * @param message The message to enqueue
+     * @param sessionId Optional session ID for binding the operation to a specific session
+     * @param maxSize Optional maximum queue size - if specified and queue is full, throws an error
+     * @throws Error if maxSize is specified and would be exceeded
+     */
+    enqueue(taskId: string, message: QueuedMessage, sessionId?: string, maxSize?: number): Promise<void>;
+    /**
+     * Removes and returns the first message from the queue for a specific task.
+     * @param taskId The task identifier
+     * @param sessionId Optional session ID for binding the query to a specific session
+     * @returns The first message, or undefined if the queue is empty
+     */
+    dequeue(taskId: string, sessionId?: string): Promise<QueuedMessage | undefined>;
+    /**
+     * Removes and returns all messages from the queue for a specific task.
+     * Used when tasks are cancelled or failed to clean up pending messages.
+     * @param taskId The task identifier
+     * @param sessionId Optional session ID for binding the query to a specific session
+     * @returns Array of all messages that were in the queue
+     */
+    dequeueAll(taskId: string, sessionId?: string): Promise<QueuedMessage[]>;
+}
+/**
+ * Task creation options.
+ * @experimental
+ */
+export interface CreateTaskOptions {
+    /**
+     * Time in milliseconds to keep task results available after completion.
+     * If null, the task has unlimited lifetime until manually cleaned up.
+     */
+    ttl?: number | null;
+    /**
+     * Time in milliseconds to wait between task status requests.
+     */
+    pollInterval?: number;
+    /**
+     * Additional context to pass to the task store.
+     */
+    context?: Record<string, unknown>;
+}
+/**
+ * Interface for storing and retrieving task state and results.
+ *
+ * Similar to Transport, this allows pluggable task storage implementations
+ * (in-memory, database, distributed cache, etc.).
+ *
+ * @experimental
+ */
+export interface TaskStore {
+    /**
+     * Creates a new task with the given creation parameters and original request.
+     * The implementation must generate a unique taskId and createdAt timestamp.
+     *
+     * TTL Management:
+     * - The implementation receives the TTL suggested by the requestor via taskParams.ttl
+     * - The implementation MAY override the requested TTL (e.g., to enforce limits)
+     * - The actual TTL used MUST be returned in the Task object
+     * - Null TTL indicates unlimited task lifetime (no automatic cleanup)
+     * - Cleanup SHOULD occur automatically after TTL expires, regardless of task status
+     *
+     * @param taskParams - The task creation parameters from the request (ttl, pollInterval)
+     * @param requestId - The JSON-RPC request ID
+     * @param request - The original request that triggered task creation
+     * @param sessionId - Optional session ID for binding the task to a specific session
+     * @returns The created task object
+     */
+    createTask(taskParams: CreateTaskOptions, requestId: RequestId, request: Request, sessionId?: string): Promise<Task>;
+    /**
+     * Gets the current status of a task.
+     *
+     * @param taskId - The task identifier
+     * @param sessionId - Optional session ID for binding the query to a specific session
+     * @returns The task object, or null if it does not exist
+     */
+    getTask(taskId: string, sessionId?: string): Promise<Task | null>;
+    /**
+     * Stores the result of a task and sets its final status.
+     *
+     * @param taskId - The task identifier
+     * @param status - The final status: 'completed' for success, 'failed' for errors
+     * @param result - The result to store
+     * @param sessionId - Optional session ID for binding the operation to a specific session
+     */
+    storeTaskResult(taskId: string, status: 'completed' | 'failed', result: Result, sessionId?: string): Promise<void>;
+    /**
+     * Retrieves the stored result of a task.
+     *
+     * @param taskId - The task identifier
+     * @param sessionId - Optional session ID for binding the query to a specific session
+     * @returns The stored result
+     */
+    getTaskResult(taskId: string, sessionId?: string): Promise<Result>;
+    /**
+     * Updates a task's status (e.g., to 'cancelled', 'failed', 'completed').
+     *
+     * @param taskId - The task identifier
+     * @param status - The new status
+     * @param statusMessage - Optional diagnostic message for failed tasks or other status information
+     * @param sessionId - Optional session ID for binding the operation to a specific session
+     */
+    updateTaskStatus(taskId: string, status: Task['status'], statusMessage?: string, sessionId?: string): Promise<void>;
+    /**
+     * Lists tasks, optionally starting from a pagination cursor.
+     *
+     * @param cursor - Optional cursor for pagination
+     * @param sessionId - Optional session ID for binding the query to a specific session
+     * @returns An object containing the tasks array and an optional nextCursor
+     */
+    listTasks(cursor?: string, sessionId?: string): Promise<{
+        tasks: Task[];
+        nextCursor?: string;
+    }>;
+}
+/**
+ * Checks if a task status represents a terminal state.
+ * Terminal states are those where the task has finished and will not change.
+ *
+ * @param status - The task status to check
+ * @returns True if the status is terminal (completed, failed, or cancelled)
+ * @experimental
+ */
+export declare function isTerminal(status: Task['status']): boolean;
+//# sourceMappingURL=interfaces.d.ts.map