execute_transition
Facilitates role transitions by executing transitions, providing execution status, and essential details for next steps. Requires transition ID, task ID, and role ID inputs.
Instructions
Executes role transition and returns execution status with essential details for next steps.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| handoffMessage | No | Optional handoff message | |
| roleId | Yes | Role ID for transition context | |
| taskId | Yes | Task ID for transition context | |
| transitionId | Yes | Transition ID to execute |
Input Schema (JSON Schema)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"handoffMessage": {
"description": "Optional handoff message",
"type": "string"
},
"roleId": {
"description": "Role ID for transition context",
"type": "string"
},
"taskId": {
"description": "Task ID for transition context",
"type": "number"
},
"transitionId": {
"description": "Transition ID to execute",
"type": "string"
}
},
"required": [
"transitionId",
"taskId",
"roleId"
],
"type": "object"
}
Implementation Reference
- Zod input schema and inferred TypeScript type for the execute_transition tool.const ExecuteTransitionInputSchema = z.object({ transitionId: z.string().describe('Transition ID to execute'), taskId: z.number().describe('Task ID for transition context'), roleId: z.string().describe('Role ID for transition context'), handoffMessage: z.string().optional().describe('Optional handoff message'), }); type GetRoleTransitionsInput = z.infer<typeof GetRoleTransitionsInputSchema>; type ValidateTransitionInput = z.infer<typeof ValidateTransitionInputSchema>; type ExecuteTransitionInput = z.infer<typeof ExecuteTransitionInputSchema>;
- Registration of the execute_transition MCP tool using @Tool decorator with name, description, and schema.@Tool({ name: 'execute_transition', description: `Executes role transition and returns execution status with essential details for next steps.`, parameters: ExecuteTransitionInputSchema as ZodSchema<ExecuteTransitionInput>, })
- Main handler function for execute_transition tool: processes input, calls RoleTransitionService.executeTransition, updates workflow context cache, and returns structured MCP response.async executeTransition(input: ExecuteTransitionInput) { try { const context = { taskId: input.taskId.toString(), roleId: input.roleId, }; const result = await this.roleTransitionService.executeTransition( input.transitionId, context, input.handoffMessage, ); // π§ UPDATE WORKFLOW CONTEXT CACHE // Store latest workflow state after successful transition if (result.success && result.newRoleId) { try { // Try to find existing cache entry to update const existingContext = this.workflowContextCache.findContextByTaskId( input.taskId, ); const cacheKey = existingContext ? WorkflowContextCacheService.generateKey( existingContext.executionId, 'transition', ) : WorkflowContextCacheService.generateKey( `task-${input.taskId}`, 'transition', ); this.workflowContextCache.updateContext(cacheKey, { currentRoleId: result.newRoleId, }); } catch (_cacheError) { // Don't fail transition if cache update fails } } // β MINIMAL RESPONSE: Only essential execution data return this.buildResponse({ transitionId: input.transitionId, success: result.success, status: result.success ? 'completed' : 'failed', message: result.message, newRoleId: result.newRoleId, }); } catch (error) { return this.buildErrorResponse( 'Failed to execute transition', getErrorMessage(error), 'TRANSITION_EXECUTION_ERROR', ); } }
- Core helper service method implementing the transition logic: validates transition, records it, updates task ownership and workflow execution state.async executeTransition( transitionId: string, context: { roleId: string; taskId: string; projectPath?: string }, handoffMessage?: string, ): Promise<{ success: boolean; message: string; newRoleId?: string }> { try { // First validate the transition const validation = await this.validateTransition(transitionId, context); if (!validation.valid) { return { success: false, message: `Transition validation failed: ${validation.errors.join(', ')}`, }; } const transition = await this.workflowRoleRepository.findTransitionById(transitionId); if (!transition) { return { success: false, message: 'Transition not found' }; } // Record the transition in the task workflow await this.recordTransition(transition, context, handoffMessage); // Update task ownership if needed await this.updateTaskOwnership( String(context.taskId), transition.toRole.name, ); // π§ FIX: Update workflow execution state after role transition await this.updateWorkflowExecutionStateForTransition( context.taskId, transition.toRole.id, handoffMessage, ); return { success: true, message: `Successfully transitioned from ${transition.fromRole.description} to ${transition.toRole.description}`, newRoleId: transition.toRole.id, }; } catch (error) { return { success: false, message: `Transition execution failed: ${error.message}`, }; } }