MCP Task

Instructions

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,
  ],