check_task_status

Monitor the progress and retrieve partial results of a running AI task by providing its task ID, enabling real-time status updates for complex workflows.

Instructions

Check the status of a running task. Returns current status, progress, and partial results if available.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`task_id`	Yes	The task ID returned from run_task

Implementation Reference

src/serve.ts:598-704 (handler)

Handler for check_task_status tool. Retrieves task status from TaskManager, computes live progress, recent activity, warnings for stuck tasks, recommended re-check interval, and returns comprehensive JSON status report.

case 'check_task_status': {
    if (!args.task_id) {
        throw new Error('task_id is required');
    }

    const task = taskManager.getTask(args.task_id);
    if (!task) {
        throw new Error(`Task ${args.task_id} not found`);
    }

    // Check for stuck task indicators
    let warningMessage = null;
    if (task.status === 'running') {
        const now = Date.now();

        // Check last activity time
        if (task.lastActivityTime) {
            const inactiveTime =
                now - task.lastActivityTime.getTime();
            if (inactiveTime > 60000) {
                // 1 minute
                warningMessage = `Warning: No activity for ${Math.round(inactiveTime / 1000)} seconds`;
            }
        }

        // Check runtime
        if (task.startedAt) {
            const runtime = now - task.startedAt.getTime();
            if (runtime > 5 * 60 * 1000) {
                // 5 minutes
                warningMessage = `Warning: Task running for ${Math.round(runtime / 60000)} minutes`;
            }
        }

        // Check error count
        if (task.errorCount && task.errorCount > 2) {
            warningMessage = `Warning: ${task.errorCount} errors encountered`;
        }
    }

    // Calculate recommended check_after based on task runtime
    let recommendedCheckAfter = 120; // Default max of 2 minutes
    if (task.status === 'running' && task.startedAt) {
        const runtimeMs = Date.now() - task.startedAt.getTime();
        const runtimeSeconds = Math.floor(runtimeMs / 1000);

        // Progressive backoff: 5s for first 5s, 10s for first 10s, then scale up
        if (runtimeSeconds <= 5) {
            recommendedCheckAfter = 5;
        } else if (runtimeSeconds <= 10) {
            recommendedCheckAfter = 10;
        } else if (runtimeSeconds <= 30) {
            recommendedCheckAfter = 15;
        } else if (runtimeSeconds <= 60) {
            recommendedCheckAfter = 30;
        } else if (runtimeSeconds <= 120) {
            recommendedCheckAfter = 60;
        } else {
            recommendedCheckAfter = 120; // Max 2 minutes for long-running tasks
        }
    }

    // Get live progress for running tasks using taskStatus()
    let currentProgress = null;
    if (task.status === 'running') {
        currentProgress = await taskManager.getTaskProgress(
            args.task_id
        );
    }

    const activity = taskManager.getTaskActivity(args.task_id);

    return {
        content: [
            {
                type: 'text',
                text: JSON.stringify(
                    {
                        id: task.id,
                        status: task.status,
                        model: task.model || task.modelClass,
                        readOnly: task.readOnly,
                        createdAt: task.createdAt,
                        startedAt: task.startedAt,
                        completedAt: task.completedAt,
                        output: task.output, // Shows result if complete, error if failed
                        progress: currentProgress || task.progress, // Live status from taskStatus() or cached
                        messageCount: task.messages.length,
                        requestCount: task.requestCount || 0,
                        recentEvents: activity.recentEvents,
                        toolCalls: activity.toolCalls,
                        lastActivity: activity.lastActivity,
                        check_after:
                            task.status === 'running'
                                ? `Please wait ${recommendedCheckAfter} seconds before checking this task again`
                                : null,
                        warning: warningMessage,
                        errorCount: task.errorCount,
                        lastError: task.lastError,
                    },
                    null,
                    2
                ),
            },
        ],
    };
}

src/serve.ts:171-192 (schema)

Tool schema definition for check_task_status, including name, description, annotations, and input schema requiring task_id.

const CHECK_TASK_STATUS_TOOL: Tool = {
    name: 'check_task_status',
    description:
        'Check the status of a running task. Returns current status, progress, and partial results if available.',
    annotations: {
        title: 'Check Task Status',
        readOnlyHint: true, // Only reads task status
        destructiveHint: false, // Doesn't modify or destroy data
        idempotentHint: false, // task_id returns status each time
        openWorldHint: false, // Only queries local task state
    },
    inputSchema: {
        type: 'object',
        properties: {
            task_id: {
                type: 'string',
                description: 'The task ID returned from run_task',
            },
        },
        required: ['task_id'],
    },
};

src/serve.ts:563-570 (registration)

Registration of check_task_status in the list of available tools returned by ListToolsRequestSchema handler.

tools: [
    RUN_TASK_TOOL,
    CHECK_TASK_STATUS_TOOL,
    GET_TASK_RESULT_TOOL,
    CANCEL_TASK_TOOL,
    WAIT_FOR_TASK_TOOL,
    LIST_TASKS_TOOL,
],

MCP Task