check_task_status
Monitor the progress and retrieve the status of a long-running AI task. Obtain current status, updates, and partial results for efficient workflow management.
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)Main execution handler for check_task_status tool. Fetches task details from TaskManager, computes progress, activity, warnings, recommended polling interval, and returns comprehensive JSON status including recent events and tool calls.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)TypeScript type definition and JSON schema for the check_task_status tool, including input validation for task_id parameter, descriptions, and MCP annotations.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:558-579 (registration)Registers check_task_status tool by including it in the tools array returned from the MCP ListToolsRequestSchema handler.server.setRequestHandler(ListToolsRequestSchema, async () => { if (process.env.MCP_MODE !== 'true') { logger.debug('Received ListTools request'); } const response = { tools: [ RUN_TASK_TOOL, CHECK_TASK_STATUS_TOOL, GET_TASK_RESULT_TOOL, CANCEL_TASK_TOOL, WAIT_FOR_TASK_TOOL, LIST_TASKS_TOOL, ], }; if (process.env.MCP_MODE !== 'true') { logger.debug( 'Returning tools:', response.tools.map(t => t.name) ); } return response; });
- src/utils/task-manager.ts:269-311 (helper)Helper method in TaskManager that provides live task progress by calling external taskStatus function, with rate limiting and caching.public async getTaskProgress(taskId: string): Promise<string | null> { const task = this.tasks.get(taskId); if (!task) { return null; } // Can't call taskStatus on completed/failed/cancelled tasks if ( task.status !== 'running' || !task.taskGenerator || !task.taskAgent ) { return task.progress || null; } // Rate limit status updates (max once per second) const now = new Date(); if (task.lastStatusUpdate) { const timeSinceLastUpdate = now.getTime() - task.lastStatusUpdate.getTime(); if (timeSinceLastUpdate < 1000) { return task.progress || null; } } try { const statusEvent = await taskStatus( task.taskGenerator, task.taskAgent ); task.progress = statusEvent.summary; task.lastStatusUpdate = now; logger.debug( `Updated status for task ${taskId}: ${statusEvent.summary}` ); return statusEvent.summary; } catch (error: any) { logger.debug( `Could not get task status for ${taskId}: ${error.message}` ); return task.progress || null; } }