@nitrostack/core 1.0.1 → 1.0.2

package/dist/core/task.d.ts

@@ -0,0 +1,280 @@
+import { Logger } from './types.js';
+/**
+ * Task status values as per MCP spec
+ *
+ * Lifecycle:
+ * - `working` → `input_required` | `completed` | `failed` | `cancelled`
+ * - `input_required` → `working` | `completed` | `failed` | `cancelled`
+ * - `completed`, `failed`, `cancelled` are terminal — no further transitions
+ */
+export type TaskStatus = 'working' | 'input_required' | 'completed' | 'failed' | 'cancelled';
+/**
+ * Terminal statuses — tasks in these states cannot transition further
+ */
+export declare const TERMINAL_STATUSES: TaskStatus[];
+/**
+ * Check if a status is terminal
+ */
+export declare function isTerminalStatus(status: TaskStatus): boolean;
+/**
+ * Task data structure as per MCP spec
+ */
+export interface TaskData {
+    /** Unique identifier for the task */
+    taskId: string;
+    /** Current state of the task execution */
+    status: TaskStatus;
+    /** Optional human-readable message describing the current state */
+    statusMessage?: string;
+    /** ISO 8601 timestamp when the task was created */
+    createdAt: string;
+    /** ISO 8601 timestamp when the task status was last updated */
+    lastUpdatedAt: string;
+    /** Time in milliseconds from creation before task may be deleted */
+    ttl: number | null;
+    /** Suggested time in milliseconds between status checks */
+    pollInterval?: number;
+}
+/**
+ * Task parameters that can be sent with a task-augmented request
+ */
+export interface TaskParams {
+    /** Requested TTL in milliseconds */
+    ttl?: number;
+}
+/**
+ * Related task metadata for associating messages with tasks
+ */
+export interface RelatedTaskMeta {
+    taskId: string;
+}
+/**
+ * CreateTaskResult — returned when a task-augmented request is accepted
+ */
+export interface CreateTaskResult {
+    task: TaskData;
+}
+/**
+ * Task execution support level for tools
+ */
+export type TaskSupportLevel = 'required' | 'optional' | 'forbidden';
+/**
+ * TaskManager handles the full lifecycle of MCP tasks.
+ *
+ * It provides:
+ * - In-memory task storage with TTL-based cleanup
+ * - Task creation, status updates, and result retrieval
+ * - Cancellation support
+ * - Status change notifications via callbacks
+ *
+ * @example
+ * ```typescript
+ * const taskManager = new TaskManager({ logger, defaultTtl: 60000 });
+ *
+ * // Create a task for a long-running operation
+ * const task = taskManager.createTask({ ttl: 120000 });
+ *
+ * // Update status as work progresses
+ * taskManager.updateStatus(task.taskId, 'working', 'Processing step 2 of 5');
+ *
+ * // Complete with result
+ * taskManager.completeTask(task.taskId, { data: 'result' });
+ * ```
+ */
+export declare class TaskManager {
+    private tasks;
+    private logger;
+    private defaultTtl;
+    private defaultPollInterval;
+    private cleanupInterval?;
+    private onStatusChange?;
+    constructor(options: {
+        logger: Logger;
+        /** Default TTL in ms (default: 300000 = 5 minutes) */
+        defaultTtl?: number;
+        /** Default poll interval in ms (default: 2000 = 2 seconds) */
+        defaultPollInterval?: number;
+        /** Callback fired on every status change (for notifications) */
+        onStatusChange?: (taskData: TaskData) => void;
+    });
+    /**
+     * Create a new task
+     */
+    createTask(params?: TaskParams, toolName?: string): TaskData;
+    /**
+     * Get task data by ID
+     * @throws Error if task not found
+     */
+    getTask(taskId: string): TaskData;
+    /**
+     * Update task status
+     * @throws Error if transition is invalid
+     */
+    updateStatus(taskId: string, status: TaskStatus, statusMessage?: string): TaskData;
+    /**
+     * Complete a task with a successful result
+     */
+    completeTask(taskId: string, result: unknown, statusMessage?: string): TaskData;
+    /**
+     * Fail a task with an error
+     */
+    failTask(taskId: string, error: {
+        code: number;
+        message: string;
+        data?: unknown;
+    }, statusMessage?: string): TaskData;
+    /**
+     * Cancel a task
+     * @throws Error if task is already in a terminal state
+     */
+    cancelTask(taskId: string): TaskData;
+    /**
+     * Get the result of a completed task.
+     * If the task is still working, this blocks until it reaches a terminal state.
+     */
+    getResult(taskId: string): Promise<{
+        result?: unknown;
+        error?: {
+            code: number;
+            message: string;
+            data?: unknown;
+        };
+    }>;
+    /**
+     * Get the AbortSignal for a task (useful for cancellation-aware handlers)
+     */
+    getAbortSignal(taskId: string): AbortSignal;
+    /**
+     * List all tasks with optional cursor-based pagination
+     */
+    listTasks(cursor?: string, limit?: number): {
+        tasks: TaskData[];
+        nextCursor?: string;
+    };
+    /**
+     * Check if a task exists
+     */
+    hasTask(taskId: string): boolean;
+    /**
+     * Cleanup expired tasks
+     */
+    private cleanupExpiredTasks;
+    /**
+     * Get internal entry or throw
+     */
+    private getEntry;
+    /**
+     * Validate a status transition
+     */
+    private validateTransition;
+    /**
+     * Stop the cleanup interval (call on server shutdown)
+     */
+    destroy(): void;
+}
+/**
+ * TaskContext provides a developer-friendly interface for working with tasks
+ * inside tool handlers. It wraps the TaskManager and provides simple methods
+ * to update progress and check for cancellation.
+ *
+ * @example
+ * ```typescript
+ * const tool = new Tool({
+ *   name: 'process_data',
+ *   taskSupport: 'optional',
+ *   handler: async (input, context) => {
+ *     const task = context.task; // TaskContext if task-augmented
+ *
+ *     if (task) {
+ *       task.updateProgress('Starting data processing...');
+ *
+ *       for (let i = 0; i < items.length; i++) {
+ *         task.throwIfCancelled(); // Throws if client cancelled
+ *         await processItem(items[i]);
+ *         task.updateProgress(`Processed ${i + 1}/${items.length} items`);
+ *       }
+ *     }
+ *
+ *     return { processed: items.length };
+ *   }
+ * });
+ * ```
+ */
+export declare class TaskContext {
+    private taskManager;
+    private _taskId;
+    private _abortSignal;
+    constructor(taskManager: TaskManager, taskId: string);
+    /** The task ID */
+    get taskId(): string;
+    /** AbortSignal that triggers when the task is cancelled */
+    get abortSignal(): AbortSignal;
+    /** Whether the task has been cancelled */
+    get isCancelled(): boolean;
+    /**
+     * Update the task status message (keeps status as 'working')
+     */
+    updateProgress(message: string): void;
+    /**
+     * Transition to input_required status
+     */
+    requestInput(message: string): void;
+    /**
+     * Throw a TaskCancelledError if the task has been cancelled.
+     * Call this periodically in long-running handlers to support cancellation.
+     */
+    throwIfCancelled(): void;
+    /**
+     * Get the current task data
+     */
+    getTaskData(): TaskData;
+}
+/**
+ * Task not found error (maps to JSON-RPC -32602)
+ */
+export declare class TaskNotFoundError extends Error {
+    readonly taskId: string;
+    readonly code = -32602;
+    constructor(taskId: string);
+}
+/**
+ * Task already in terminal state error (maps to JSON-RPC -32602)
+ */
+export declare class TaskAlreadyTerminalError extends Error {
+    readonly taskId: string;
+    readonly status: TaskStatus;
+    readonly code = -32602;
+    constructor(taskId: string, status: TaskStatus);
+}
+/**
+ * Invalid task status transition error
+ */
+export declare class InvalidTaskTransitionError extends Error {
+    readonly fromStatus: TaskStatus;
+    readonly toStatus: TaskStatus;
+    readonly code = -32603;
+    constructor(fromStatus: TaskStatus, toStatus: TaskStatus);
+}
+/**
+ * Task cancelled error (thrown by throwIfCancelled())
+ */
+export declare class TaskCancelledError extends Error {
+    readonly taskId: string;
+    constructor(taskId: string);
+}
+/**
+ * Task augmentation required error (maps to JSON-RPC -32600)
+ */
+export declare class TaskAugmentationRequiredError extends Error {
+    readonly code = -32600;
+    constructor();
+}
+/**
+ * Task expired error (maps to JSON-RPC -32602)
+ */
+export declare class TaskExpiredError extends Error {
+    readonly taskId: string;
+    readonly code = -32602;
+    constructor(taskId: string);
+}
+//# sourceMappingURL=task.d.ts.map

package/dist/core/task.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../src/core/task.ts"],"names":[],"mappings":"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"}

package/dist/core/task.js

@@ -0,0 +1,414 @@
+import { v4 as uuidv4 } from 'uuid';
+/**
+ * Terminal statuses — tasks in these states cannot transition further
+ */
+export const TERMINAL_STATUSES = ['completed', 'failed', 'cancelled'];
+/**
+ * Check if a status is terminal
+ */
+export function isTerminalStatus(status) {
+    return TERMINAL_STATUSES.includes(status);
+}
+// ============================================================================
+// Task Manager
+// ============================================================================
+/**
+ * TaskManager handles the full lifecycle of MCP tasks.
+ *
+ * It provides:
+ * - In-memory task storage with TTL-based cleanup
+ * - Task creation, status updates, and result retrieval
+ * - Cancellation support
+ * - Status change notifications via callbacks
+ *
+ * @example
+ * ```typescript
+ * const taskManager = new TaskManager({ logger, defaultTtl: 60000 });
+ *
+ * // Create a task for a long-running operation
+ * const task = taskManager.createTask({ ttl: 120000 });
+ *
+ * // Update status as work progresses
+ * taskManager.updateStatus(task.taskId, 'working', 'Processing step 2 of 5');
+ *
+ * // Complete with result
+ * taskManager.completeTask(task.taskId, { data: 'result' });
+ * ```
+ */
+export class TaskManager {
+    tasks = new Map();
+    logger;
+    defaultTtl;
+    defaultPollInterval;
+    cleanupInterval;
+    onStatusChange;
+    constructor(options) {
+        this.logger = options.logger;
+        this.defaultTtl = options.defaultTtl ?? 300000; // 5 minutes
+        this.defaultPollInterval = options.defaultPollInterval ?? 2000;
+        this.onStatusChange = options.onStatusChange;
+        // Start periodic cleanup of expired tasks
+        this.cleanupInterval = setInterval(() => this.cleanupExpiredTasks(), 30000);
+    }
+    /**
+     * Create a new task
+     */
+    createTask(params, toolName) {
+        const taskId = uuidv4();
+        const now = new Date().toISOString();
+        const ttl = params?.ttl ?? this.defaultTtl;
+        let resolveCompletion;
+        const completionPromise = new Promise((resolve) => {
+            resolveCompletion = resolve;
+        });
+        const data = {
+            taskId,
+            status: 'working',
+            createdAt: now,
+            lastUpdatedAt: now,
+            ttl,
+            pollInterval: this.defaultPollInterval,
+        };
+        const entry = {
+            data,
+            abortController: new AbortController(),
+            completionPromise,
+            resolveCompletion: resolveCompletion,
+            toolName,
+        };
+        this.tasks.set(taskId, entry);
+        this.logger.info(`Task created: ${taskId}`, { toolName });
+        return { ...data };
+    }
+    /**
+     * Get task data by ID
+     * @throws Error if task not found
+     */
+    getTask(taskId) {
+        const entry = this.getEntry(taskId);
+        return { ...entry.data };
+    }
+    /**
+     * Update task status
+     * @throws Error if transition is invalid
+     */
+    updateStatus(taskId, status, statusMessage) {
+        const entry = this.getEntry(taskId);
+        // Validate transition
+        this.validateTransition(entry.data.status, status);
+        entry.data.status = status;
+        entry.data.lastUpdatedAt = new Date().toISOString();
+        if (statusMessage !== undefined) {
+            entry.data.statusMessage = statusMessage;
+        }
+        // If terminal, resolve the completion promise
+        if (isTerminalStatus(status)) {
+            entry.resolveCompletion();
+        }
+        this.logger.info(`Task ${taskId} status: ${status}`, { statusMessage });
+        // Fire notification callback
+        if (this.onStatusChange) {
+            this.onStatusChange({ ...entry.data });
+        }
+        return { ...entry.data };
+    }
+    /**
+     * Complete a task with a successful result
+     */
+    completeTask(taskId, result, statusMessage) {
+        const entry = this.getEntry(taskId);
+        entry.result = result;
+        return this.updateStatus(taskId, 'completed', statusMessage ?? 'Task completed successfully');
+    }
+    /**
+     * Fail a task with an error
+     */
+    failTask(taskId, error, statusMessage) {
+        const entry = this.getEntry(taskId);
+        entry.error = error;
+        return this.updateStatus(taskId, 'failed', statusMessage ?? `Task failed: ${error.message}`);
+    }
+    /**
+     * Cancel a task
+     * @throws Error if task is already in a terminal state
+     */
+    cancelTask(taskId) {
+        const entry = this.getEntry(taskId);
+        if (isTerminalStatus(entry.data.status)) {
+            throw new TaskAlreadyTerminalError(taskId, entry.data.status);
+        }
+        // Signal cancellation
+        entry.abortController.abort();
+        return this.updateStatus(taskId, 'cancelled', 'The task was cancelled by request.');
+    }
+    /**
+     * Get the result of a completed task.
+     * If the task is still working, this blocks until it reaches a terminal state.
+     */
+    async getResult(taskId) {
+        const entry = this.getEntry(taskId);
+        // If not terminal, wait for completion
+        if (!isTerminalStatus(entry.data.status)) {
+            await entry.completionPromise;
+        }
+        // Re-fetch after awaiting (status may have changed)
+        const current = this.getEntry(taskId);
+        if (current.error) {
+            return { error: current.error };
+        }
+        return { result: current.result };
+    }
+    /**
+     * Get the AbortSignal for a task (useful for cancellation-aware handlers)
+     */
+    getAbortSignal(taskId) {
+        const entry = this.getEntry(taskId);
+        return entry.abortController.signal;
+    }
+    /**
+     * List all tasks with optional cursor-based pagination
+     */
+    listTasks(cursor, limit = 50) {
+        const allTasks = Array.from(this.tasks.values())
+            .map(e => ({ ...e.data }))
+            .sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+        let startIndex = 0;
+        if (cursor) {
+            const cursorIndex = allTasks.findIndex(t => t.taskId === cursor);
+            if (cursorIndex === -1) {
+                throw new TaskNotFoundError(cursor);
+            }
+            startIndex = cursorIndex + 1;
+        }
+        const page = allTasks.slice(startIndex, startIndex + limit);
+        const nextCursor = startIndex + limit < allTasks.length
+            ? allTasks[startIndex + limit - 1]?.taskId
+            : undefined;
+        return { tasks: page, nextCursor };
+    }
+    /**
+     * Check if a task exists
+     */
+    hasTask(taskId) {
+        return this.tasks.has(taskId);
+    }
+    /**
+     * Cleanup expired tasks
+     */
+    cleanupExpiredTasks() {
+        const now = Date.now();
+        for (const [taskId, entry] of this.tasks.entries()) {
+            if (entry.data.ttl === null)
+                continue; // Unlimited TTL
+            const createdTime = new Date(entry.data.createdAt).getTime();
+            if (now - createdTime > entry.data.ttl) {
+                this.tasks.delete(taskId);
+                this.logger.debug(`Expired task cleaned up: ${taskId}`);
+            }
+        }
+    }
+    /**
+     * Get internal entry or throw
+     */
+    getEntry(taskId) {
+        const entry = this.tasks.get(taskId);
+        if (!entry) {
+            throw new TaskNotFoundError(taskId);
+        }
+        return entry;
+    }
+    /**
+     * Validate a status transition
+     */
+    validateTransition(from, to) {
+        if (isTerminalStatus(from)) {
+            throw new InvalidTaskTransitionError(from, to);
+        }
+        // Same-status self-transitions are allowed for progress message updates
+        // (e.g., working → working just to update statusMessage)
+        if (from === to)
+            return;
+        // Valid transitions:
+        // working → input_required | completed | failed | cancelled
+        // input_required → working | completed | failed | cancelled
+        const validTransitions = {
+            working: ['input_required', 'completed', 'failed', 'cancelled'],
+            input_required: ['working', 'completed', 'failed', 'cancelled'],
+        };
+        const allowed = validTransitions[from];
+        if (!allowed || !allowed.includes(to)) {
+            throw new InvalidTaskTransitionError(from, to);
+        }
+    }
+    /**
+     * Stop the cleanup interval (call on server shutdown)
+     */
+    destroy() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = undefined;
+        }
+    }
+}
+// ============================================================================
+// Task Context Helper
+// ============================================================================
+/**
+ * TaskContext provides a developer-friendly interface for working with tasks
+ * inside tool handlers. It wraps the TaskManager and provides simple methods
+ * to update progress and check for cancellation.
+ *
+ * @example
+ * ```typescript
+ * const tool = new Tool({
+ *   name: 'process_data',
+ *   taskSupport: 'optional',
+ *   handler: async (input, context) => {
+ *     const task = context.task; // TaskContext if task-augmented
+ *
+ *     if (task) {
+ *       task.updateProgress('Starting data processing...');
+ *
+ *       for (let i = 0; i < items.length; i++) {
+ *         task.throwIfCancelled(); // Throws if client cancelled
+ *         await processItem(items[i]);
+ *         task.updateProgress(`Processed ${i + 1}/${items.length} items`);
+ *       }
+ *     }
+ *
+ *     return { processed: items.length };
+ *   }
+ * });
+ * ```
+ */
+export class TaskContext {
+    taskManager;
+    _taskId;
+    _abortSignal;
+    constructor(taskManager, taskId) {
+        this.taskManager = taskManager;
+        this._taskId = taskId;
+        this._abortSignal = taskManager.getAbortSignal(taskId);
+    }
+    /** The task ID */
+    get taskId() {
+        return this._taskId;
+    }
+    /** AbortSignal that triggers when the task is cancelled */
+    get abortSignal() {
+        return this._abortSignal;
+    }
+    /** Whether the task has been cancelled */
+    get isCancelled() {
+        return this._abortSignal.aborted;
+    }
+    /**
+     * Update the task status message (keeps status as 'working')
+     */
+    updateProgress(message) {
+        try {
+            this.taskManager.updateStatus(this._taskId, 'working', message);
+        }
+        catch {
+            // Task may have been cancelled/cleaned up — ignore
+        }
+    }
+    /**
+     * Transition to input_required status
+     */
+    requestInput(message) {
+        this.taskManager.updateStatus(this._taskId, 'input_required', message);
+    }
+    /**
+     * Throw a TaskCancelledError if the task has been cancelled.
+     * Call this periodically in long-running handlers to support cancellation.
+     */
+    throwIfCancelled() {
+        if (this._abortSignal.aborted) {
+            throw new TaskCancelledError(this._taskId);
+        }
+    }
+    /**
+     * Get the current task data
+     */
+    getTaskData() {
+        return this.taskManager.getTask(this._taskId);
+    }
+}
+// ============================================================================
+// Task Errors
+// ============================================================================
+/**
+ * Task not found error (maps to JSON-RPC -32602)
+ */
+export class TaskNotFoundError extends Error {
+    taskId;
+    code = -32602;
+    constructor(taskId) {
+        super(`Failed to retrieve task: Task not found`);
+        this.taskId = taskId;
+        this.name = 'TaskNotFoundError';
+    }
+}
+/**
+ * Task already in terminal state error (maps to JSON-RPC -32602)
+ */
+export class TaskAlreadyTerminalError extends Error {
+    taskId;
+    status;
+    code = -32602;
+    constructor(taskId, status) {
+        super(`Cannot cancel task: already in terminal status '${status}'`);
+        this.taskId = taskId;
+        this.status = status;
+        this.name = 'TaskAlreadyTerminalError';
+    }
+}
+/**
+ * Invalid task status transition error
+ */
+export class InvalidTaskTransitionError extends Error {
+    fromStatus;
+    toStatus;
+    code = -32603;
+    constructor(fromStatus, toStatus) {
+        super(`Invalid task status transition: ${fromStatus} → ${toStatus}`);
+        this.fromStatus = fromStatus;
+        this.toStatus = toStatus;
+        this.name = 'InvalidTaskTransitionError';
+    }
+}
+/**
+ * Task cancelled error (thrown by throwIfCancelled())
+ */
+export class TaskCancelledError extends Error {
+    taskId;
+    constructor(taskId) {
+        super(`Task ${taskId} was cancelled`);
+        this.taskId = taskId;
+        this.name = 'TaskCancelledError';
+    }
+}
+/**
+ * Task augmentation required error (maps to JSON-RPC -32600)
+ */
+export class TaskAugmentationRequiredError extends Error {
+    code = -32600;
+    constructor() {
+        super('Task augmentation required for tools/call requests');
+        this.name = 'TaskAugmentationRequiredError';
+    }
+}
+/**
+ * Task expired error (maps to JSON-RPC -32602)
+ */
+export class TaskExpiredError extends Error {
+    taskId;
+    code = -32602;
+    constructor(taskId) {
+        super(`Failed to retrieve task: Task has expired`);
+        this.taskId = taskId;
+        this.name = 'TaskExpiredError';
+    }
+}
+//# sourceMappingURL=task.js.map