get_batch_status

Instructions

Implementation Reference

• src/tools/get_batch_status.ts:30-70 (handler)

  The main handler function `handleGetBatchStatus`. Validates that `batch_operation_id` is a non-empty string, retrieves the operation from the in-memory store via `getBatchOperation()`, and returns either `{found: false, message: ...}` or `{found: true, operation: ...}`.

  export async function handleGetBatchStatus(
    input: GetBatchStatusInput
  ): Promise<GetBatchStatusOutput> {
    // ============================================================================
    // Step 1: Validate input
    // ============================================================================
    if (!input || typeof input !== 'object') {
      throw new ValidationError('input is required and must be an object', 'input');
    }
  
    if (
      !input.batch_operation_id ||
      typeof input.batch_operation_id !== 'string' ||
      input.batch_operation_id.trim() === ''
    ) {
      throw new ValidationError(
        'batch_operation_id is required and must be a non-empty string',
        'batch_operation_id'
      );
    }
  
    // ============================================================================
    // Step 2: Retrieve operation from store
    // ============================================================================
    const operation = getBatchOperation(input.batch_operation_id);
  
    // ============================================================================
    // Step 3: Return result
    // ============================================================================
    if (!operation) {
      return {
        found: false,
        message: `Batch operation "${input.batch_operation_id}" not found. Operations are kept in memory for 1 hour after completion.`,
      };
    }
  
    return {
      found: true,
      operation,
    };
  }

• src/types/index.ts:703-705 (schema)

  Input schema `GetBatchStatusInput`: expects a required `batch_operation_id` string.

  export interface GetBatchStatusInput {
    batch_operation_id: string;
  }

• src/types/index.ts:707-711 (schema)

  Output schema `GetBatchStatusOutput`: `found` boolean, optional `operation` (BatchOperation), and optional `message` string.

  export interface GetBatchStatusOutput {
    found: boolean;
    operation?: BatchOperation;
    message?: string;
  }

• src/types/index.ts:687-700 (schema)

  The `BatchOperation` interface used in the output, containing operation state: id, type, status, progress, successful_ids, failed_items, timestamps.

  export interface BatchOperation {
    batch_operation_id: string;
    operation_type: 'update' | 'delete' | 'import' | 'dartql';
    status: 'running' | 'completed' | 'failed';
    progress: {
      completed: number;
      total: number;
      percent: number;
    };
    successful_ids: string[];
    failed_items: Array<{ id?: string; row_number?: number; error: string }>;
    started_at: string;
    completed_at?: string;
    execution_time_ms?: number;

• src/index.ts:608-621 (registration)

  Tool registration in `ListToolsRequestSchema` handler: defines the `get_batch_status` tool with name, description, and inputSchema requiring `batch_operation_id`.

  {
    name: 'get_batch_status',
    description: 'Retrieve status of a batch operation (update, delete, import, or dartql) by batch_operation_id. Operations are kept in memory for 1 hour.',
    inputSchema: {
      type: 'object',
      properties: {
        batch_operation_id: {
          type: 'string',
          description: 'Batch operation ID returned from batch_update_tasks, batch_delete_tasks, or import_tasks_csv',
        },
      },
      required: ['batch_operation_id'],
    },
  },

• src/index.ts:1088-1098 (registration)

  Tool call dispatch in `CallToolRequestSchema` handler: the `case 'get_batch_status'` block that calls `handleGetBatchStatus` and returns JSON-stringified result.

  case 'get_batch_status': {
    const result = await handleGetBatchStatus((args || {}) as any);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  }

• src/batch/batchOperations.ts:108-110 (helper)

  Helper function `getBatchOperation()`: looks up a `BatchOperation` by ID from the in-memory Map store.

  export function getBatchOperation(batchOperationId: string): BatchOperation | undefined {
    return batchOperations.get(batchOperationId);
  }

• src/tools/info.ts:94-96 (helper)

  Discovery listing of `get_batch_status` in the `task-batch` tool group for user-facing help.

    name: 'get_batch_status',
    description: 'Get status of a long-running batch operation by batch_operation_id',
  },