feat: lock 2026-07-28 specification and schema (#19)

schema/2026-07-28/schema.ts

@@ -0,0 +1,350 @@
+/**
+ * MCP Tasks Extension Schema (spec.types.ts)
+ * Extension Identifier: io.modelcontextprotocol/tasks
+ *
+ * This file contains pure TypeScript interface definitions for the MCP Tasks extension.
+ * These types are the source of truth and are used to generate Zod schemas via `ts-to-zod`.
+ *
+ * - Use `@description` JSDoc tags to generate `.describe()` calls on schemas
+ * - This released snapshot is immutable; make changes in schema/draft/ instead
+ *
+ * @see https://modelcontextprotocol.io/seps/2663-tasks-extension
+ */
+
+import type {
+  Error as JSONRPCErrorObject,
+  InputRequests,
+  InputResponses,
+  JSONRPCNotification,
+  JSONRPCRequest,
+  NotificationParams,
+  Result,
+} from "./spec.types.js";
+
+/* Tasks */
+
+/**
+ * The status of a task.
+ *
+ * @category `tasks`
+ */
+export type TaskStatus =
+  | "working" // The request is currently being processed
+  | "input_required" // The task is waiting for input (e.g., elicitation or sampling)
+  | "completed" // The request completed successfully and results are available
+  | "failed" // The associated request failed due to a JSON-RPC error during execution
+  | "cancelled"; // The request was cancelled before completion
+
+/**
+ * Data associated with a task.
+ *
+ * @category `tasks`
+ */
+export interface Task {
+  /**
+   * The task identifier.
+   */
+  taskId: string;
+
+  /**
+   * Current task status.
+   */
+  status: TaskStatus;
+
+  /**
+   * Optional human-readable message describing the current task state.
+   * This can provide context for any status, including:
+   * - Progress descriptions for "working"
+   * - Work blocked on "input_required"
+   * - Reasons for "cancelled" status
+   * - Summaries for "completed" status
+   * - Diagnostic information for "failed" status (e.g., error details, what went wrong)
+   */
+  statusMessage?: string;
+
+  /**
+   * ISO 8601 timestamp when the task was created.
+   */
+  createdAt: string;
+
+  /**
+   * ISO 8601 timestamp when the task was last updated.
+   */
+  lastUpdatedAt: string;
+
+  /**
+   * Time-to-live duration from creation in integer milliseconds, null for unlimited.
+   * The server may discard the task after the TTL elapses. This value MAY change
+   * over the lifetime of a task.
+   * @format int
+   * @nullable
+   */
+  ttlMs: number | null;
+
+  /**
+   * Suggested polling interval in integer milliseconds. Clients SHOULD honor
+   * this value to avoid overwhelming the server. This value MAY change over
+   * the lifetime of a task.
+   * @format int
+   */
+  pollIntervalMs?: number;
+}
+
+/* Detailed Task Variants */
+
+/**
+ * A task that is in a normal working state.
+ * Used by tasks/get and notifications/tasks.
+ *
+ * @category `tasks`
+ */
+export interface WorkingTask extends Task {
+  status: "working";
+}
+
+/**
+ * A task that is waiting for input from the client.
+ * Used by tasks/get and notifications/tasks.
+ *
+ * @category `tasks`
+ */
+export interface InputRequiredTask extends Task {
+  status: "input_required";
+
+  /**
+   * Server-to-client requests that need to be fulfilled during task execution.
+   * Keys are arbitrary identifiers for matching requests to responses.
+   */
+  inputRequests: InputRequests;
+}
+
+/**
+ * A task that has completed successfully.
+ * Used by tasks/get and notifications/tasks.
+ *
+ * @category `tasks`
+ */
+export interface CompletedTask extends Task {
+  status: "completed";
+
+  /**
+   * The final result of the task.
+   * The structure matches the result type of the original request.
+   * For example, a CallToolRequest task would return the CallToolResult structure.
+   */
+  result: { [key: string]: unknown };
+}
+
+/**
+ * A task that has failed due to a JSON-RPC error during execution.
+ * Used by tasks/get and notifications/tasks.
+ *
+ * @category `tasks`
+ */
+export interface FailedTask extends Task {
+  status: "failed";
+
+  /**
+   * The JSON-RPC error that caused the task to fail.
+   */
+  error: JSONRPCErrorObject;
+}
+
+/**
+ * A task that has been cancelled.
+ * Used by tasks/get and notifications/tasks.
+ *
+ * @category `tasks`
+ */
+export interface CancelledTask extends Task {
+  status: "cancelled";
+}
+
+/**
+ * A union type representing a task with status-specific fields inlined.
+ * This type is used by tasks/get responses and notifications/tasks
+ * notifications to provide complete task state including terminal results
+ * or pending input requests.
+ *
+ * @category `tasks`
+ */
+export type DetailedTask =
+  | WorkingTask
+  | InputRequiredTask
+  | CompletedTask
+  | FailedTask
+  | CancelledTask;
+
+/* Task Creation */
+
+/**
+ * The result returned by a server in lieu of a standard result shape when
+ * it elects to process a request asynchronously. The resultType field MUST
+ * be set to "task". This type is Result & Task (flat).
+ *
+ * @category `tasks`
+ */
+export type CreateTaskResult = Result &
+  Task & {
+    /**
+     * Discriminator distinguishing a task handle from a standard result.
+     */
+    resultType: "task";
+  };
+
+/* Task Operations */
+
+/**
+ * A request to retrieve the state of a task.
+ *
+ * @category `tasks/get`
+ */
+export type GetTaskRequest = JSONRPCRequest & {
+  method: "tasks/get";
+  params: {
+    /**
+     * The task identifier to query.
+     */
+    taskId: string;
+  };
+};
+
+/**
+ * The response to a tasks/get request. Carries the appropriate DetailedTask
+ * variant for the task's current status. The resultType field MUST be set
+ * to "complete".
+ *
+ * @category `tasks/get`
+ */
+export type GetTaskResult = Result &
+  DetailedTask & {
+    /**
+     * Discriminator marking this as the standard result shape for tasks/get.
+     */
+    resultType: "complete";
+  };
+
+/**
+ * A request to provide input responses to a task in the input_required state.
+ *
+ * @category `tasks/update`
+ */
+export type UpdateTaskRequest = JSONRPCRequest & {
+  method: "tasks/update";
+  params: {
+    /**
+     * The task identifier to update.
+     */
+    taskId: string;
+
+    /**
+     * Responses to outstanding inputRequests previously surfaced by the server.
+     * Each key MUST correspond to a currently-outstanding inputRequest key.
+     */
+    inputResponses: InputResponses;
+  };
+};
+
+/**
+ * The response to a tasks/update request. An empty acknowledgement.
+ * The resultType field MUST be set to "complete".
+ *
+ * @category `tasks/update`
+ */
+export type UpdateTaskResult = Result & {
+  /**
+   * Discriminator marking this as the standard result shape for tasks/update.
+   */
+  resultType: "complete";
+};
+
+/**
+ * A request to cancel a task.
+ *
+ * @category `tasks/cancel`
+ */
+export type CancelTaskRequest = JSONRPCRequest & {
+  method: "tasks/cancel";
+  params: {
+    /**
+     * The task identifier to cancel.
+     */
+    taskId: string;
+  };
+};
+
+/**
+ * The response to a tasks/cancel request. An empty acknowledgement.
+ * Cancellation is cooperative and eventually consistent.
+ * The resultType field MUST be set to "complete".
+ *
+ * @category `tasks/cancel`
+ */
+export type CancelTaskResult = Result & {
+  /**
+   * Discriminator marking this as the standard result shape for tasks/cancel.
+   */
+  resultType: "complete";
+};
+
+/* Task Notifications */
+
+/**
+ * Parameters for a `notifications/tasks` notification.
+ * Carries a complete DetailedTask for the current status.
+ *
+ * @category `notifications/tasks`
+ */
+export type TaskStatusNotificationParams = NotificationParams &
+  DetailedTask & { [key: string]: unknown };
+
+/**
+ * An optional notification from the server to the client, informing it that
+ * a task's status has changed. Servers are not required to send these notifications.
+ * Clients subscribe via subscriptions/listen.
+ *
+ * @category `notifications/tasks`
+ */
+export type TaskStatusNotification = JSONRPCNotification & {
+  method: "notifications/tasks";
+  params: TaskStatusNotificationParams;
+};
+
+/* Subscription Additions */
+
+/**
+ * Task-specific fields for the subscriptions/listen request.
+ * Clients include tasksStatus to subscribe to notifications/tasks
+ * for specific task IDs.
+ *
+ * @category `subscriptions`
+ */
+export interface TaskSubscriptionNotifications {
+  /**
+   * Subscribe to notifications/tasks for specific task IDs.
+   */
+  taskIds?: string[];
+}
+
+/**
+ * Task-specific fields for the notifications/subscriptions/acknowledged notification.
+ * The server includes the list of task IDs it has agreed to send status notifications for.
+ *
+ * @category `subscriptions`
+ */
+export interface TaskSubscriptionAcknowledgedNotifications {
+  /**
+   * Task IDs the server has agreed to send status notifications for.
+   */
+  taskIds?: string[];
+}
+
+/* Extension Capability */
+
+/**
+ * The extension capability declaration for the tasks extension.
+ * An empty object indicates support; no extension-specific settings are currently defined.
+ *
+ * @category `tasks`
+ */
+export type TasksExtensionCapability = Record<string, never>;